AGENTS.md Contract
Each generated template now ships with an AGENTS.md file— a focused operating contract for AI assistants (Cursor, Copilot Chat, PR bots) powered by agents.md.
Purpose
Separate human docs from AI guidance
Humans read README + docs/*. AI assistants read AGENTS.md for rules, guardrails, and execution steps.
Guardrails
Reduce hallucinations + unsafe changes
Explicit refusal cases, escalation triggers, and validation reminders keep AI changes scoped + safe.
Workflow
Reinforce expected execution flow
Encourages read-before-write, plan-before-apply, and explicit assumption surfacing.
Generated Example (React Template)
A trimmed example of the AGENTS.md shipped with a React Vite template.
# AGENTS.md – AI Interaction & Execution Guide (Human contributors: see CONTRIBUTING.md & docs/)
This file is intentionally scoped **only** for AI assistants (Cursor, Copilot Chat, PR automation bots).
Humans: read CONTRIBUTING.md and the documents under docs/.
## 1. Authoritative References (Never Reproduce Content Here)
| Topic | Source of Truth |
|-------|-----------------|
| Project architecture | docs/PROJECT_STRUCTURE.md |
| Component patterns | docs/COMPONENT_GUIDELINES.md |
| Performance guidance | docs/PERFORMANCE.md |
| State management approach | docs/STATE_MANAGEMENT.md |
| Styling + design system | docs/STYLING.md |
| Testing strategy | docs/TESTING.md |
| Accessibility notes | docs/ACCESSIBILITY.md |
## 2. Operating Principles (AI Perspective)
- Documentation-first
- Reuse-before-build
- Type safety always (no unvetted any)
- Deterministic, incremental changes
- Explicit assumption logging
## 3. AI Execution Protocol (React Feature Work)
When asked to add/modify UI logic:
1. Locate relevant feature folder (src/features/*) or propose new if justified
2. Read related docs/* referenced above
3. Prefer extending existing component patterns
4. Show proposed file tree + diff plan BEFORE writing code
5. After code: list follow-up validation steps (lint, type check, test)
## 4. Guardrails (Must Enforce)
- Do NOT fabricate file paths, component APIs, or library versions
- Do NOT remove existing accessibility props (aria-*, alt, role) without replacement rationale
- Do NOT introduce global mutable singletons for state—prefer documented patterns
- ALWAYS flag large dependency additions (>1 lib) for human confirmation
- ALWAYS surface potential performance regressions (unmemoized large lists, heavy renders)
## 5. Component Creation Checklist
- Typed props interface exported
- Meaningful name + colocated index.ts re-export (if pattern exists)
- Accessibility reviewed (labels, semantics)
- Story / example or usage snippet considered
- Test file added or explicitly deferred with reason
## 6. When the AI Should Ask or Refuse
Ask for clarification if: feature scope unclear, conflicting patterns, missing target directory.
Refuse if: asked to bypass validation, remove type safety, duplicate existing documented component.
## 7. Post-Change Assistant Report
Return a bullet summary:
- Files touched (concise)
- New dependencies (if any)
- Type/lint status
- Suggested manual QA steps
- Deferred items (tests, docs)
---
Maintained automatically by create-awesome-node-app React template provisioning.
Humans: stop reading—go to CONTRIBUTING.md + docs/.
Customizing Your AGENTS.md
Adapting for your team
Feel free to extend sections (Guardrails, Protocol, Refusal Conditions) but avoid duplicating rich procedural docs—link to existing sources instead.
- Add domain-specific escalation triggers (security, data, billing)
- Reference internal design system docs instead of re-stating variants
- Include CI scripts or task runners (e.g.
pnpm test:unit) if not obvious - Keep tone imperative and concise—optimize for machine parsing + embedding