AGENTS.md & CLAUDE.md Generator

What You'll Do

Generate two files for the repository:

1. AGENTS.md — Cross-tool agent instructions following the open standard (https://agents.md). Supported by Claude Code, Cursor, Windsurf, Zed, GitHub Copilot, OpenAI Codex, Aider, and many others. This is the primary file containing project context, conventions, and workflows.
2. CLAUDE.md — Claude Code-specific configuration that references AGENTS.md via @import and adds any Claude-specific instructions. This avoids duplicating content across two files.

Why two files?

• AGENTS.md is the cross-tool standard — any AI coding tool reads it. Put all project knowledge here.
• CLAUDE.md is Claude Code-specific. It should be thin: point to AGENTS.md and only add what's Claude-unique.
• This means you maintain docs in one place (AGENTS.md) and every tool benefits.

---

Reference Documentation

Always prefer pointing users to these docs rather than reciting their contents:

• AGENTS.md spec: https://agents.md
• CLAUDE.md memory docs: https://code.claude.com/docs/en/memory
• CLAUDE.md guide (Builder.io): https://www.builder.io/blog/claude-md-guide

---

Phase 1 · Understand the Repository

1. Check for existing files

   • Look for existing AGENTS.md, CLAUDE.md, CLAUDE.local.md, .claude/CLAUDE.md, and .claude/rules/ in the repo.
   • If files exist, plan to update/extend rather than overwrite.

2. Read core docs

   • Skim README.md, CONTRIBUTING.md, and any docs/ directory.
   • Note project philosophy, setup steps, and workflows.

3. Survey project layout

   • Identify primary directories, languages, frameworks, and ownership.
   • Run tree --gitignore -a -L 3 to get a directory snapshot. Trim to top 2-3 levels.

4. Identify tooling and commands

   • Find the project's build, test, lint, format, and deploy commands — whatever tool the project actually uses.
   • Note environment requirements: runtimes, package managers, env vars, .env.example files.

5. Resolve ambiguities

   • Ask the developer when conventions or ownership are unclear. Do not guess.

Outcome: Structured notes covering layout, tooling, commands, testing, conventions, and open questions.

---

Phase 2 · Generate AGENTS.md

Place at the repository root. Follow this section order for consistency:

# Agent Guidelines

Brief one-line project description.

Detailed docs live in @docs/... — reference them with @imports rather than duplicating here.

## Tech Stack

- **React** - Component framework
- **TypeScript** - Language (strict mode)
- **Relay** - GraphQL data fetching
<!-- List each technology with its role in the project -->

## Common Commands

- `<lint command>` — run on changed files
- `<test command>` — run on changed files
- `<type-check command>` — verify types
- `<build command>` — production build

## Pre-Commit Verification

Before every commit, verify code quality on pending files:

\`\`\`sh
<type-check command>
<test command on changed files>
<lint command on changed files>
\`\`\`

Never commit code that fails these checks.

## Code Style

- Specific, actionable rules (not vague "follow best practices")
- Export preferences (named vs default)
- Typing strictness expectations

## Common Patterns

<!-- Map tools to purposes: "use X for Y" -->
- **UI**: Use <design system> for UI components
- **Data**: Use <data layer> for data fetching
- **Testing**: Use <test lib>, avoid <anti-pattern>

## File Organization

<!-- Annotated structure showing what goes where -->
\`\`\`
src/
├── Apps/           # Sub-applications
├── Components/     # Shared across apps
└── System/         # Framework code
\`\`\`

## Workflow

- Branching model
- PR / review expectations
- Commit message format

## Gotchas

- Non-obvious project quirks
- Common pitfalls

## Further Documentation

- [Topic](docs/topic.md)
- And more in @docs

Writing guidelines

• Keep it actionable — agents should follow instructions verbatim, not interpret vague guidance.
• "Use X for Y" — map tools to purposes so agents pick the right library.
• Exact commands — include the actual shell commands, not descriptions of what to do.
• Pre-commit checks — always include a verification block with commands to run before committing.
• Reference deeper docs — use @imports to link to detailed docs instead of duplicating content.
• Annotate the file tree — don't dump raw tree output; curate it with inline descriptions.
• Stay under 300 lines. Only include sections relevant to the project — skip empty ones.

---

Phase 3 · Generate CLAUDE.md

Place at the repository root alongside AGENTS.md. This file should be thin — its job is to point to AGENTS.md. For most projects, this is all you need:

# CLAUDE.md

See @AGENTS.md

That's often the entire file, and that's fine. Only add a Claude-specific section if the project actually uses Claude-only features:

• .claude/rules/ — references to modular rule files in the project
• .claude/commands/ — custom slash commands available in the project
• .claude/agents/ — custom subagents available in the project
• Behavioral preferences tied to Claude capabilities — e.g., "Use plan mode for non-trivial tasks", "Use subagents for parallel research"
• Tool permission hints — e.g., "You have permission to run npm test without asking"

If none of these apply, don't add them. An empty Claude-specific section is worse than no section.

Additional Claude memory features

Point the developer to the docs (https://code.claude.com/docs/en/memory) for advanced features like CLAUDE.local.md, .claude/rules/, @imports, /init, and auto memory.

---

Phase 4 · Validate & Wrap Up

1. Both files exist at the repo root.
2. CLAUDE.md references AGENTS.md via See @AGENTS.md.
3. No duplication — project knowledge lives in AGENTS.md only.
4. Commands are accurate — all listed commands actually work.
5. Concise — both files are scannable and under 300 lines.
6. Handoff summary — tell the developer what was added, flag open questions, and point to the official docs for advanced features.