Starter Template: agents.md
This is a starting point for inspiration—not a copy-paste solution. Every project is different.
Better approach: Use the 9 Things for Effective Agent-Driven Development note as context, then ask your agent: "Help me design and implement an AGENTS.md (or CLAUDE.md) for this project based on these strategies." The agent can tailor it to your stack and workflow.
Below is a template that shows the structure. Adapt sections to your repo.
# Agent Configuration
## Project Architecture
### Directory Structure
- `./app` — Next.js application (App Router)
- `./components` — Shared React components
- `./lib` — Utilities, helpers, API clients
- `./types` — TypeScript type definitions
### Key Files
- `./app/layout.tsx` — Root layout, providers, global styles
- `./lib/api.ts` — API client and data fetching
- `./components/ui/` — Base UI components
### Navigation
Before searching the codebase, check for a NAV_MAP.md or README in the target directory. Read it first to understand what each area does.
---
## Behavioral Rules
### Rule of Threes
If the same error appears 3 times in a session:
1. STOP. Do not attempt a 4th fix.
2. Analyze the root cause, not the symptom.
3. Check devlog.md for similar past issues.
4. Propose a structural fix. Log the solution to devlog.md with timestamp.
### Before Starting Any Task
1. Read devlog.md for recent context and successful patterns.
2. If a similar task was done before, ask: "Should I follow the same approach as [previous task]?"
3. Confirm scope before executing. Ask clarifying questions if the task is ambiguous.
### Before Completing Any Task
- Remove unused imports and dead code (no commenting out).
- Remove stray console.logs unless explicitly debugging.
- Keep types correct; avoid `any` unless necessary.
- If a file exceeds ~300 lines, consider splitting.
### When Stuck
1. Don't loop. If 2 attempts fail, pause and explain what's not working.
2. Ask for help or suggest an alternative. "I'm not sure" is better than guessing and breaking things.
---
## Documentation
### devlog.md Format
After significant work, append:
**What / Why / How / Learned** (brief).
### When to Update devlog.md
After fixing a tricky bug, making an architectural decision, discovering a library gotcha, or completing a multi-step feature.
---
## Sub-Agents
Spawn sub-agents for parallel, independent tasks (e.g. UI, API, tests). Give each: the specific task, relevant files to read first, and design constraints. Include "Check devlog.md before starting."
---
## Tech Stack (example)
- Next.js 15, App Router, React 19, TypeScript (strict)
- Tailwind CSS; use CSS variables for theme
- [Your DB and external services—with links to current docs]
- When referencing library APIs, confirm the version in package.json. Don't assume latest.
---
## What NOT to Do
- Don't create new files when you can edit existing ones.
- Don't add dependencies without asking.
- Don't refactor unrelated code while fixing a bug.
- Don't leave TODO comments—do it or note it in devlog.
- Don't guess at file paths—search or ask. Explore the codebase first.