diff --git a/README.md b/README.md index 686eeedb9..6fc831349 100644 --- a/README.md +++ b/README.md @@ -1,212 +1,138 @@ # AI Agent Instructions Template -**Pre-built, customizable instruction templates for AI coding agents.** This repo includes ready-to-use AGENTS.md, CLAUDE.md, and PLANS.md files with best practices already written—you just fill in your project-specific details (or let AI do it automatically). +**Pre-built templates that make AI agents write better code with less back-and-forth.** -**Don't start from scratch.** Clone these pre-written templates and customize them for your project in minutes, not hours. +## The Problem +AI coding agents (Claude Code, Cursor, Copilot, Windsurf) produce higher-quality code when they understand your project's architecture, conventions, and tech stack. But explaining this context every time—or writing instruction docs from scratch—wastes hours. -**Works with:** Claude Code, Cursor, GitHub Copilot, Windsurf, and more. +## This Solution +Ready-to-use instruction templates (AGENTS.md, CLAUDE.md, PLANS.md) with best practices already written. You customize project-specific details quickly, and your AI agent immediately: +- ✅ Follows your patterns without repeated prompting +- ✅ Handles simple requests instantly with context +- ✅ Auto-generates execution plans for complex features +- ✅ Scales across your team with zero per-request overhead + +**ROI:** 5-minute setup saves 2+ hours/week in context-explaining and back-and-forth. --- -## Quick Start +## 5-Minute Setup -### 1. Clone This Repository +### 1. Clone This Repo ```bash git clone https://github.com/YOUR_USERNAME/agent-instructions.git -cd agent-instructions ``` -You now have pre-written AGENTS.md, CLAUDE.md, and PLANS.md templates ready to customize. - -### 2. Customize Templates +### 2. Auto-Fill Templates with Metaprompt -**Option A: AI Auto-Fill (Recommended)** +**What the metaprompt does:** Scans the current directory's codebase and automatically fills `[YOUR_*]` placeholders in AGENTS.md and CLAUDE.md. -Share `metaprompt.txt` with your AI agent and ask: +**How to use it:** -> *"Please analyze this project and populate all AGENTS.md and CLAUDE.md files using the metaprompt instructions"* +1. **Navigate to the directory** where you want AI instructions (root, `backend/`, `frontend/`, etc.) + ```bash + cd agent-instructions/backend # or frontend, or stay in root + ``` -The AI will detect your tech stack, analyze your structure, and auto-fill all `[YOUR_*]` placeholders. +2. **Open your AI coding assistant** in that directory -**Option B: Manual Customization** +3. **Share** `prompts/metaprompt.txt` -Browse the template files and replace `[YOUR_*]` placeholders with your project details. The templates already have structure, examples, and guidelines—you just fill in the specifics. +4. **Say:** *"Fill in AGENTS.md and CLAUDE.md for this directory using the metaprompt"* -### 3. Configure Your AI Agent +The AI analyzes the focused context (tech stack, patterns, dependencies in that directory) and populates templates in ~2 minutes. -**Claude Code:** -```bash -# CLAUDE.md is automatically loaded from root - already configured! +**Before/After Example:** ``` - -**Cursor:** -```bash -cp AGENTS.md .cursorrules +Before: [YOUR_FRAMEWORK], [YOUR_DATABASE] +After: Express, PostgreSQL ``` -**GitHub Copilot:** -```bash -mkdir -p .github && cp AGENTS.md .github/copilot-instructions.md -``` +**Repeat for each directory** where you want AI instructions (backend, frontend, etc.). -**Windsurf:** -```bash -cp AGENTS.md .windsurfrules -``` +### 3. Link Templates to Your AI Agent + +**Claude Code:** Already configured (reads CLAUDE.md automatically) +**Cursor:** `cp AGENTS.md .cursorrules` +**GitHub Copilot:** `cp AGENTS.md .github/copilot-instructions.md` +**Windsurf:** `cp AGENTS.md .windsurfrules` + +--- + +## How It Works + +### One-Time Setup, Zero Ongoing Overhead -### 4. Start Coding +Once configured, templates provide context for **every request** automatically. -Your AI agent now understands your project structure, tech stack, and conventions. +**Simple requests:** Handled instantly with AGENTS.md context +- "Add error handling to login" → AI knows your patterns, no explanation needed +- "Fix TypeScript error" → AI understands your type system +- "Refactor component" → AI follows established conventions + +**Complex features:** AI auto-generates structured execution plans +- "Build notification system" → Creates detailed plan in `specs/`, implements systematically +- "Add real-time collaboration" → Designs architecture, validates before coding + +**You don't write individual plans.** Templates handle straightforward work. AI creates plans only when complexity requires it. + +### Optional: DeepWiki Integration + +Enable DeepWiki in CLAUDE.md for AI to consult best practices when planning complex features: +- Architecture patterns (microservices, event-driven, caching) +- Library-specific guidance (React, PostgreSQL, Redis) + +**Example:** Designing rate-limiting → DeepWiki surfaces token bucket algorithms and proven patterns. --- ## What's Included -**Pre-written template files with best practices built-in:** +| Component | Purpose | +|-----------|---------| +| **AGENTS.md** | Project context: architecture, tech stack, conventions (works with any AI agent) | +| **CLAUDE.md** | Claude Code-specific instructions with ExecPlan workflow | +| **PLANS.md** | Template for complex feature execution plans | +| **Metaprompt** | Auto-fills all templates by analyzing your codebase | +| **Three-tier structure** | Root + `frontend/` + `backend/` for organized mono/multi-repo support | -| Feature | Description | -|---------|-------------| -| **📝 AGENTS.md** | Comprehensive agent instructions template (architecture, tech stack, conventions) | -| **⚙️ CLAUDE.md** | Claude Code-specific template with ExecPlan methodology pre-configured | -| **📋 PLANS.md** | Complete ExecPlan framework based on OpenAI's methodology | -| **📁 Three-Tier Specs** | Organized directory structure for root, frontend, and backend specs | -| **🤖 Metaprompt** | AI tool that auto-fills all `[YOUR_*]` placeholders by analyzing your code | -| **🔍 DeepWiki Integration** | AI consults best practices for design patterns and architecture decisions | +**Result:** Professional templates with best practices built-in. You customize project specifics, not structure. -**You get:** Professional templates with sections, examples, and guidelines already written. Just customize the project-specific parts. +--- ## Repository Structure ``` . -├── metaprompt.txt # AI analyzes your project and fills templates -├── AGENTS.md # Root-level agent instructions -├── CLAUDE.md # Root-level Claude Code configuration -├── DEV_SETUP.md # Onboarding documentation template -├── specs/ # Root specs (full-stack features) -│ ├── PLANS.md -│ ├── README.md -│ └── sample-spec-1.md +├── AGENTS.md # Root-level instructions +├── CLAUDE.md # Claude Code configuration +├── prompts/metaprompt.txt # Auto-fill tool +├── specs/ # Full-stack feature plans +│ └── PLANS.md ├── backend/ │ ├── AGENTS.md │ ├── CLAUDE.md -│ └── specs/ # Backend-only features +│ └── specs/ # Backend-only plans └── frontend/ ├── AGENTS.md ├── CLAUDE.md - └── specs/ # Frontend-only features + └── specs/ # Frontend-only plans ``` -## Why Use This? - -**Problem:** AI agents produce better code when they understand your project, but writing instructions from scratch takes hours. - -**Solution:** Start with pre-written templates containing best practices, then customize just the project-specific parts. Or use the metaprompt to auto-fill everything. - -**What you get:** -- ✅ **Templates, not blank files** - Architecture sections, code style guidelines, testing approaches already written -- ✅ **Example placeholders** - Clear `[YOUR_FRAMEWORK]` markers show exactly what to customize -- ✅ **AI auto-fill** - Metaprompt analyzes your code and populates templates automatically -- ✅ **Multi-agent support** - Works with Claude Code, Cursor, Copilot, Windsurf - -**Results:** -- ⚡ Minutes to configure, not hours of writing from scratch -- 🎯 Professional structure with proven best practices -- 📈 Consistent AI output across your entire team - ---- - -## Key Concepts - -### Three-Tier Specs Structure - -Organize implementation plans by scope: -- **`specs/`**: Full-stack features spanning frontend and backend -- **`frontend/specs/`**: Frontend-only features and changes -- **`backend/specs/`**: Backend-only features and changes - -### ExecPlans (Execution Plans) - -PLANS.md based on [OpenAI's Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md), for complex features: - -1. **Determine Scope**: Frontend, backend, or full-stack? -2. **Create Spec File**: Place in appropriate `specs/` directory -3. **Follow PLANS.md**: Use the structure provided -4. **Keep Self-Contained**: Include all context needed -5. **Update as You Go**: Living document approach -6. **Update README**: Link spec in `specs/README.md` - -**DeepWiki Integration:** AI agents automatically consult DeepWiki for best practices on design patterns, architecture, and implementation strategies when creating ExecPlans. This ensures your specs follow industry standards and proven patterns. - -### Using the Metaprompt - -The `metaprompt.txt` instructs AI to: -- Scan codebase for tech indicators (package.json, configs, etc.) -- Extract project info (description, commands, patterns) -- Populate all templates with accurate, project-specific data -- Validate completeness (no placeholders left) - -**When to use:** -- Initial setup after forking -- After major tech stack changes -- When documentation becomes outdated - --- ## FAQ -**Q: Why separate AGENTS.md files for backend/frontend?** -A: Different tech stacks, conventions, and tools. Separate files = focused instructions. Root-level file helps agents determine scope. - -**Q: AGENTS.md vs CLAUDE.md?** -A: AGENTS.md works with any AI agent. CLAUDE.md is specifically for Claude Code with ExecPlan methodology built-in. - -**Q: Why three specs directories?** -A: Clear separation, smart organization, reduced complexity. Frontend/backend teams work independently. Full-stack features go in root `specs/`. - -**Q: Can I use this for a monorepo?** -A: Yes! Place AGENTS.md and CLAUDE.md in each package. The three-tier specs structure scales well. +**Q: Why separate files for backend/frontend?** +A: Different tech stacks need focused context. Keeps instructions clean and AI responses accurate. -**Q: Metaprompt or manual?** -A: Metaprompt (fast, accurate) or manual (more control). Many teams use metaprompt for initial setup, then refine manually. - -**Q: Can I delete ExecPlans?** -A: Yes, delete PLANS.md files and specs directories if not using. But try it first - many teams find it valuable. +**Q: What if I have a simple single-tier project?** +A: Just use root-level AGENTS.md and CLAUDE.md. Delete backend/frontend directories. --- -## Best Practices - -**For AI Agents:** -1. Read full AGENTS.md before starting work -2. Follow documented patterns -3. Use ExecPlans for complex features -4. Update documentation when making architectural changes - -**For Developers:** -1. Keep instructions current -2. Be specific, not vague -3. Include code examples -4. Document exceptions -5. Version control your instructions - ---- - -## Credits - -- **PLANS.md**: Based on [Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md) -- **Metaprompt**: Inspired by meta-prompting for AI-assisted documentation -- **Three-tier architecture**: Designed for scalable full-stack projects - -## License - -MIT License - see [LICENSE](LICENSE) file for details. - -## Contributing - -Fork, improve, submit PR. Issues specific to your project should be handled in your fork. - ---- +**License:** MIT +**Credits:** PLANS.md based on [OpenAI's Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md) -**Ready?** Fork this repo, run the metaprompt, and give your AI agents the context they need! 🚀 +Ready? Clone, run the metaprompt, and give your AI agents the context they need. 🚀