Starter Template: agents.md

Feb 3, 2026

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.

Back to 9 Things for Effective Agent-Driven Development.

# 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.