Starter Template: agents.md

# 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
- Related project: `../backend` — API server (reference when needed)
 
### Key Files
- `./app/layout.tsx` — Root layout, providers, global styles
- `./lib/api.ts` — API client and data fetching
- `./components/ui/` — Base UI components (buttons, inputs, etc.)
 
### Navigation
Before searching the codebase, check if a `NAV_MAP.md` exists in the target directory. If it does, read it first—it explains what each file does.
 
---
 
## Behavioral Rules
 
### Rule of Threes
If you encounter the same error 3 times in a session:
1. STOP. Do not attempt a 4th fix.
2. Step back and analyze the root cause, not the symptom.
3. Check devlog.md for similar past issues.
4. Propose a structural fix, not a band-aid.
5. 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 completed 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
Run these checks:
- Unused imports? Remove them.
- Dead code? Delete it entirely (no commenting out).
- Console.logs left behind? Remove unless explicitly debugging.
- Types correct? No `any` unless absolutely necessary.
- File too long (>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 approach.
3. It's better to say "I'm not sure" than to guess and break things.
 
---
 
## Documentation
 
### devlog.md Format
After significant work, append an entry:
 
\`\`\`
## [YYYY-MM-DD] Brief Title
 
**What:** One sentence describing what was done.
**Why:** The reasoning or problem it solved.
**How:** Key implementation details (if non-obvious).
**Learned:** Any gotchas or patterns discovered.
\`\`\`
 
### When to Update devlog.md
- After fixing a tricky bug
- After making an architectural decision
- After discovering a gotcha with a library
- After completing a multi-step feature
 
### Referencing Past Work
When starting related work, I may say: "Check devlog entry from [date] about [topic]—follow that approach."
 
---
 
## Sub-Agents
 
### When to Spawn Sub-Agents
Spawn sub-agents for parallel, independent tasks. Example:
- "Build the UI for feature X" → UI sub-agent
- "Write API routes for feature X" → API sub-agent
- "Write tests for feature X" → Testing sub-agent
 
### Sub-Agent Instructions
When spawning a sub-agent, include:
1. The specific task (not the whole project)
2. Relevant files to read first
3. Design constraints or patterns to follow
4. "Check devlog.md before starting"
 
### Sub-Agent Configs (if using)
- `agents/ui.md` — UI component standards, styling rules
- `agents/api.md` — API patterns, error handling, auth
- `agents/testing.md` — Test structure, mocking patterns
 
---
 
## Tech Stack
 
### Framework
- Next.js 15 with App Router
- React 19
- TypeScript (strict mode)
 
### Styling
- Tailwind CSS
- Class order: layout → spacing → sizing → colors → effects
- Use CSS variables for theme colors
 
### Database
- [Your DB here]
- Docs: [link to current docs]
- IMPORTANT: Do not rely on training data for API specifics. Reference the docs link above.
 
### External Services
- [Service]: [docs link]
- [Service]: [docs link]
 
### Version Pinning
When referencing library APIs, confirm the version in package.json first. Don't assume latest syntax.
 
---
 
## Code Style
 
### File Organization
- One component per file
- Colocate tests: `Component.tsx` + `Component.test.tsx`
- Colocate styles if using CSS modules: `Component.module.css`
 
### Naming
- Components: PascalCase (`UserProfile.tsx`)
- Utilities: camelCase (`formatDate.ts`)
- Constants: SCREAMING_SNAKE_CASE
- Types/Interfaces: PascalCase with descriptive names (`UserProfileProps`)
 
### Imports
Order:
1. React/Next.js
2. External libraries
3. Internal absolute imports (@/...)
4. Relative imports
5. Types (with `type` keyword)
 
### Error Handling
- Use try/catch for async operations
- Provide meaningful error messages
- Log errors with context, not just the error object
 
---
 
## 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—either do it or note it in devlog
- Don't guess at file paths—use search or ask
- Don't assume the codebase structure—explore first