agents-md

AGENTS.md Best Practices

Create production-ready AGENTS.md files following best practices below.

When to Use

• User asks to create or update AGENTS.md files
• Need to implement quality gates or agent documentation
• Even if they just say "add an AGENTS.md" or "set up agent guidance"

Quick Start

Basic:

cat > AGENTS.md << 'EOF'
# AGENTS.md
## Named Constants
readonly MAX_FILE_SIZE=500

## Setup
- Install: npm install
- Test: npm test

## Code Style
- TypeScript strict
- Max line: 100
EOF

Production: See guide in agents-docs/ folder

Core Sections

1. Named Constants

## Named Constants
readonly MAX_FILE_SIZE=500
readonly TIMEOUT_SECONDS=30
readonly MAX_RETRIES=3

2. Pre-existing Issue Policy

## Pre-existing Issues
**Fix ALL before completing:**
- [ ] Lint warnings
- [ ] Test failures
- [ ] Security vulnerabilities

4. Development Workflow Rules

## Development Workflow
**Prerequisite**: Always fetch and pull the latest default remote branch before analyzing or making changes.
**Phase 1 (ANALYZE)**: Use TRIZ, write an ADR in `plans/`. (Human review required for ADR only)
**Phase 2 (DECOMPOSE)**: Plan tasks in `plans/GOAP_STATE.md`
**Phase 3 (EXECUTE)**: Implement using atomic commits. Loop until all GitHub Actions (CI checks) pass.
**Phase 4 (SYNTHESIZE)**: Update context using existing learnings.

3. Quality Gate

## Quality Gate
```bash
npm run typecheck
npm run lint
npm run test
npm audit

## Tier Structure

- **Tier 1 (Essential):** Constants, setup, style, testing
- **Tier 2 (Professional):** Add quality gate, atomic commit, security
- **Tier 3 (Enterprise):** Add skills, sub-agents, nested AGENTS.md

See `agents-docs/SKILLS.md` for tier details.

## Best Practices

### DO:
- Define named constants at top
- Include pre-existing issue policy
- Specify quality gate commands
- Reference @agents-docs/ for detail

### DON'T:
- Use magic numbers
- Skip pre-existing issues
- Write vague commands ("run tests")
- Duplicate README content