AGENTS.md Template

Overview

Brief description of the project, its purpose, and what problem it solves.

Project: [Project Name]
Type: [Web App | API | Library | CLI | etc.]
Primary Language: [TypeScript | Python | Go | etc.]
Framework: [Next.js | FastAPI | etc.]

Architecture Summary

High-level description of the system architecture. Link to C4 diagrams if available.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   API       │────▶│  Database   │
└─────────────┘     └─────────────┘     └─────────────┘

Key Components

Coding Conventions

Style Guide

• Formatting: [Prettier | Black | gofmt] with config in [location]
• Linting: [ESLint | Ruff | golangci-lint] — run npm run lint
• Naming:
  • Files: kebab-case.ts
  • Components: PascalCase
  • Functions: camelCase
  • Constants: SCREAMING_SNAKE_CASE

Patterns We Use

• Error Handling: [Describe pattern, e.g., “Result types, never throw”]
• State Management: [e.g., “Zustand for client, React Query for server”]
• Testing: [e.g., “Vitest for unit, Playwright for E2E”]
• API Design: [e.g., “REST with OpenAPI, versioned endpoints”]

Patterns to Avoid

• ❌ Don’t use any type — use unknown and narrow
• ❌ Don’t mutate state directly — use immutable updates
• ❌ Don’t add dependencies without discussing in RFC
• ❌ Don’t bypass the ORM with raw SQL unless necessary

Project Structure

src/
├── api/           # API routes and handlers
├── components/    # Reusable UI components
├── db/            # Database schema and migrations
├── lib/           # Shared utilities and helpers
├── services/      # Business logic layer
└── types/         # TypeScript type definitions

Important Files

Common Tasks

Adding a New API Endpoint

1. Define types in src/types/
2. Add route in src/api/routes.ts
3. Implement handler in src/api/handlers/
4. Add tests in __tests__/api/
5. Update OpenAPI spec

Adding a Database Migration

1
2
3
4
5

# Create migration
npx prisma migrate dev --name <migration-name>

# Apply in production
npx prisma migrate deploy

Running Tests

1
2
3

npm run test        # Unit tests
npm run test:e2e    # End-to-end tests
npm run test:cov    # With coverage

Boundaries & Guardrails

Safe to Modify

• ✅ Files in src/components/ — UI components
• ✅ Files in src/lib/ — Utility functions
• ✅ Test files in __tests__/

Requires Caution

• ⚠️ src/db/schema.prisma — Always create migration
• ⚠️ src/api/ — Consider backwards compatibility
• ⚠️ .env files — Never commit secrets

Do Not Modify

• 🚫 node_modules/ — Managed by package manager
• 🚫 Generated files in dist/ or .next/
• 🚫 CI/CD configs without team review

Dependencies

Adding New Dependencies

Before adding a dependency:

1. Check if functionality exists in current deps
2. Evaluate bundle size impact
3. Check maintenance status and security
4. Discuss in team chat for significant additions

Key Dependencies

Environment Setup

Required Tools

• Node.js >= 20
• pnpm >= 8
• Docker (for local database)

Local Development

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Install dependencies
pnpm install

# Start database
docker-compose up -d db

# Run migrations
pnpm db:migrate

# Start dev server
pnpm dev

Additional Context

Related Documentation

• Architecture Decisions
• C4 Diagrams
• API Documentation

Team Contacts

This file should be updated whenever significant architectural changes are made.