Skip to content

update readme instructions #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lavaman131 merged 1 commit into from
Oct 31, 2025
Merged

update readme instructions #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 82 additions & 156 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. 🚀