agents-md

When to Use

• Creating an AGENTS.md for a new microservice, app, or infrastructure component
• Establishing context boundaries so agents/subagents understand their scope
• Referencing skills that are relevant to a specific component
• Defining what an agent SHOULD and SHOULD NOT know about

Core Concept: Agent Hierarchy

AGENTS.md (root)                    ← Global norms, skill registry, project overview
├── api/AGENTS.md                   ← Backend architecture, shared API conventions
│   ├── api/auth/AGENTS.md          ← Auth service: domain model, endpoints, config
│   ├── api/booking/AGENTS.md       ← Booking service context
│   └── api/payment/AGENTS.md       ← Payment service context
├── mobile/AGENTS.md                ← Flutter mobile conventions
├── web/AGENTS.md                   ← Flutter web conventions
└── infra/AGENTS.md                 ← Terraform / IaC conventions

Override Rule

When guidance conflicts, the most specific AGENTS.md wins:

root/AGENTS.md  <  api/AGENTS.md  <  api/auth/AGENTS.md
(general)          (backend)          (service-specific)

AGENTS.md Levels

Level 1 — Root (./AGENTS.md)

The root AGENTS.md is the single source of truth for:

• Project overview and tech stack map
• Skills registry (synced via skill-sync)
• Cross-cutting conventions (commits, PRs, code quality)
• Development setup

Already exists in this repo. Do NOT recreate. Use skill-sync to update skill tables.

Level 2 — Component ({component}/AGENTS.md)

Component-level files define architectural context for a major area:

| Component | Defines | |-----------|---------| | api/ | Microservice architecture, communication patterns, shared conventions | | mobile/ | Flutter patterns, state management, navigation | | web/ | Web-specific conventions, SSR, routing | | infra/ | IaC conventions, environments, deployment | | docs/ | Documentation standards, LaTeX compilation |

Level 3 — Service/Module ({component}/{service}/AGENTS.md)

The most specific level. Defines everything an agent needs to work on this service autonomously:

• What the service does (bounded context)
• Domain model (entities, value objects, ports)
• API surface (endpoints, request/response)
• Database schema and migrations
• Configuration and environment variables
• How to run and test locally
• What's NOT implemented (future work)
• Scoped skill references

Critical Patterns

1. Language

ALL AGENTS.md content MUST be written in English. This includes section headers, descriptions, table content, and comments. Code examples naturally remain in English.

2. Scoped Skill References

Each AGENTS.md can reference skills that are relevant to its scope. This tells agents which skills to load when working in that directory.

## Skills Reference

| Skill | Use For |
|-------|---------|
| `go-gin-handlers` | HTTP handlers, middleware, validation |
| `go-repository-pattern` | Persistence, PostgreSQL, migrations |
| `go-tdd` | Tests, mocks, table-driven tests |

Rules for scoped references:

• Only reference skills that are RELEVANT to this component
• A service AGENTS.md should reference implementation skills, not meta-skills
• Component AGENTS.md can reference broader architectural skills
• Root AGENTS.md contains the FULL registry (managed by skill-sync)

3. Required Sections by Level

Level 2 — Component AGENTS.md

| Section | Required | Purpose | |---------|----------|---------| | Overview | Yes | What this component area is | | Architecture | Yes | Patterns, layer rules, diagrams | | Service/Module Map | Yes | List of children with descriptions | | Shared Conventions | Yes | Response formats, naming, error codes | | Communication Patterns | If applicable | REST, gRPC, messaging between services | | Development Workflow | Yes | How to run, test, add new services | | Skills Reference | Yes | Scoped skills for this component |

Level 3 — Service/Module AGENTS.md

| Section | Required | Purpose | |---------|----------|---------| | Overview | Yes | What this service does, bounded context | | Tech Stack | Yes | Technologies used (table format) | | Architecture | Yes | Directory structure with annotations | | Domain Model | Yes | Entities, value objects, ports | | API Endpoints | If HTTP | Method, path, description, auth | | Error Catalog | If HTTP | Domain errors mapped to HTTP status codes | | Database | If persistent | Provider, schema, migrations | | Configuration | Yes | Env vars with defaults and descriptions | | Running | Yes | Commands to run, test, build | | What's NOT Implemented | Recommended | Future work, missing features | | Skills Reference | Optional | Service-specific skill references |

Error Catalog Convention

Every service with HTTP endpoints MUST document its error catalog. This enables agents to:

• Implement correct error handling in handlers
• Return consistent error responses across services
• Map domain errors to the right HTTP status codes

The catalog has two parts:

1. Domain Errors — internal sentinel errors defined in domain/error.go:

| Error | Description |
|-------|-------------|
| `ErrUserNotFound` | User does not exist |
| `ErrEmailTaken` | Email already registered |

2. HTTP Error Mapping — how domain errors translate to HTTP responses:

| Domain Error | HTTP Status | Error Code | Message |
|-------------|-------------|------------|---------|
| `ErrInvalidEmail` | 400 | `VALIDATION_ERROR` | Invalid email format |
| `ErrEmailTaken` | 409 | `CONFLICT` | Email already registered |
| `ErrInvalidCredentials` | 401 | `UNAUTHORIZED` | Invalid credentials |
| _(unhandled)_ | 500 | `INTERNAL_ERROR` | An unexpected error occurred |

Error codes follow the shared conventions in the parent api/AGENTS.md. Domain errors are service-specific.

4. Do NOT Duplicate Parent Context

Each level provides INCREMENTAL context. Don't repeat what the parent already says.

❌ api/auth/AGENTS.md repeating the full clean architecture explanation
✅ api/auth/AGENTS.md saying "Follows clean architecture (see api/AGENTS.md)"
   then showing the SPECIFIC directory structure for auth

5. Keep It Scannable

Agents parse AGENTS.md for quick context. Optimize for scanning:

• Use tables for structured data (endpoints, env vars, migrations)
• Use code blocks for directory trees and commands
• Use bold for key terms on first mention
• Keep descriptions to ONE line where possible
• Use --- dividers between major sections

Templates

Use the templates in assets/ as starting points:

• component-agents.md — Level 2 template for {component}/AGENTS.md
• service-agents.md — Level 3 template for {component}/{service}/AGENTS.md

Decision Tree: Do I Need an AGENTS.md?

Is this a new microservice?                          → YES, Level 3
Is this a new major component (mobile/, web/)?       → YES, Level 2
Is this a subdirectory within a service?             → NO, parent covers it
Is this a shared library or package?                 → MAYBE, if complex enough
Does the directory have unique conventions?           → YES
Does it just follow parent conventions?              → NO

Commands

# Create AGENTS.md for a new service
cp skills/agents-md/assets/service-agents.md api/{service}/AGENTS.md
# Then fill in service-specific details

# Create AGENTS.md for a new component
cp skills/agents-md/assets/component-agents.md {component}/AGENTS.md
# Then fill in component-specific details

# After creating, sync skills if you added skill references
./skills/skill-sync/assets/sync.sh

Anti-Patterns

| Don't | Do | |-------|-----| | Write AGENTS.md in Spanish or mixed languages | Write ALL content in English | | Duplicate parent context verbatim | Reference parent, add incremental details | | List every skill in every AGENTS.md | Only reference skills relevant to scope | | Write paragraphs of explanation | Use tables, code blocks, bullet points | | Include implementation code | Show directory structures and interfaces | | Describe how the code works line by line | Describe WHAT the service does and its boundaries | | Leave AGENTS.md stale after major changes | Update AGENTS.md when architecture changes |

Resources

• Templates: See assets/ for component and service AGENTS.md templates