Create Agents Md

Create prescriptive, action-oriented AGENTS.md files that tell agents what to DO, what to REUSE, and what rules to FOLLOW. Never write descriptive documentation — write instructions.

Core Philosophy

AGENTS.md files are not documentation. They are instruction sets for coding agents. Every sentence should either:

• Tell the agent what to do ("Use X when...")
• Constrain the agent's behavior ("MUST NOT...")
• Give a step-by-step procedure ("1. Create... 2. Add... 3. Run...")

File Structure Template

Every AGENTS.md follows this structure. Adapt sections based on file size (small: 40-80 lines, medium: 80-150 lines, large: 150+ lines).

# {Name} — Agent Guidelines

{One-line imperative directive: "Use X for Y." or "Use the Z module for A, B, and C."}

## MUST Rules

1. **MUST ...** — {consequence or rationale}
2. **MUST NOT ...** — {what to do instead}
3. **MUST ...** — {consequence or rationale}

## {Primary Task Section — "When You Need X" or "Adding a New Y"}

{Numbered checklist or decision table}

## {Secondary Sections}

{Tables with "When to use" / "When to modify" columns}

## Structure

{Directory tree — keep brief}

## {Cross-References} (if applicable)

- **For X**: `path/to/AGENTS.md` → Section

Prescriptive Tone Rules

NEVER start a section with

• "The module provides..."
• "This package is..."
• "This document describes..."
• "X is a Y that..."

ALWAYS start sections with

• Imperative verbs: "Use", "Add", "Create", "Configure", "Declare", "Follow", "Resolve"
• Conditional directives: "When you need X, do Y"
• Constraints: "MUST", "MUST NOT"

Transform Patterns

MUST Rules Requirements

Writing Effective MUST Rules

Each MUST rule follows this pattern: **MUST [verb]** — [rationale or consequence]

Good examples:

• **MUST resolve via DI** — always use container.resolve('cacheService'), never instantiate directly
• **MUST NOT reimplement pricing logic** — use selectBestPrice and the resolver pipeline
• **MUST export metadata** with { queue, id?, concurrency? } from every worker file
• **MUST follow document flow**: Quote → Order → Invoice — no skipping steps

Bad examples:

• **MUST** follow best practices (too vague)
• **MUST** be careful with... (not actionable)
• **MUST** use the correct approach (says nothing)

Table Column Conventions

NEVER use these column headers

• "Description"
• "Purpose" (as standalone — use "Purpose / MUST rules" instead)
• "Details"

ALWAYS use these column headers

Checklist Sections

Include numbered checklists for common tasks. Pattern: "Adding a New X" or "Checklist: Do Y"

## Adding a New Worker

1. Create worker file in `src/modules/<module>/workers/<worker-name>.ts`
2. Export `metadata` with `{ queue: '<queue-name>', id: '<worker-id>', concurrency: <n> }`
3. Export default async handler function
4. Ensure handler is idempotent — check state before mutating
5. Run `npm run modules:prepare` to register the worker
6. Test with `QUEUE_STRATEGY=local` in development

Every checklist MUST:

• Use numbered steps (not bullets)
• Start each step with an imperative verb
• Include the npm run modules:prepare step when adding module files
• End with a testing/verification step

Data Model Sections

Convert entity lists to constraint-framed bullets:

## Data Model Constraints

- **Products** — core entities with media. MUST have at least a name
- **Categories** — hierarchical. MUST maintain parent-child integrity (no circular references)
- **Variants** — linked via `product_id`. MUST reference valid option schemas
- **Prices** — multi-tier with channel scoping. MUST use `selectBestPrice` for resolution

Pattern: **Entity** — brief description. MUST [constraint]

Cross-Reference Rules

When two AGENTS.md files cover related topics:

1. Pick one authoritative source for each topic — never duplicate full content
2. Use condensed quick-references in the non-authoritative file
3. Add a Cross-Reference section at the bottom linking to related guides
4. Keep the Task Router in root AGENTS.md accurate with descriptive task names

Example:

## Cross-Reference

- **Declaring events in a module**: `packages/core/AGENTS.md` → Events
- **Queue worker contract**: `packages/queue/AGENTS.md`

File Size Guidelines

Sizing Rules

• Keep small files focused — do not pad with unnecessary sections
• Large files: keep ALL technical content, only reframe tone
• Root AGENTS.md: MUST stay under 230 lines

Code Examples in AGENTS.md

• Include code examples only for contracts (worker metadata, event declaration, subscriber export)
• Keep examples minimal — 3-5 lines max for inline snippets
• For full API examples, cross-reference the relevant module or spec
• MUST NOT include implementation details — only show the interface/pattern

Verification Checklist

After writing an AGENTS.md, verify:

1. Tone: Every section starts with imperative verb or "When you need..."
2. MUST audit: File has required number of MUST rules (3+ small, 5+ medium, 8+ large)
3. No descriptive openers: No section starts with "The module provides..." or similar
4. Tables: All tables use "When to use" / "When to modify" columns, never "Description"
5. Checklists: Common tasks have numbered step-by-step procedures
6. Data models: Entity lists are constraint-framed with MUST rules
7. Cross-references: No duplicated content between files; clear pointers instead
8. Structure section: Directory tree is present and brief
9. Opening line: File starts with one-line imperative directive, not a description

Anti-Patterns

1. Explaining how things work instead of telling agents what to do
2. Listing features instead of listing constraints
3. Duplicating content across multiple AGENTS.md files
4. Writing paragraphs where a checklist would be clearer
5. Adding changelog sections to small/medium files (only for large files with complex history)
6. Over-documenting internals — AGENTS.md guides usage, not implementation
7. Missing the "when" framing — every table/section should answer "when do I use this?"

Reference Examples

Study these files as reference implementations:

When Updating Root AGENTS.md Task Router

After creating a new AGENTS.md, update the Task Router table in root AGENTS.md:

1. Add a row with descriptive task keywords (not just the package name)
2. Include specific function names, patterns, and task verbs an agent would search for
3. Keep the root file under 230 lines