Create Agents Md

• Structure: Run ls -la and check directory organization
• Tech stack: Check package.json, Cargo.toml, pyproject.toml, go.mod, etc.
• Existing docs: Read README.md for project context
• Conventions: Look at existing code for style patterns
• CI/CD: Check .github/workflows/, Makefile, etc. for build commands

2. Structure the File

Use this template structure:

# AGENTS.md

> This file provides context for AI agents working in this codebase.
> IMPORTANT: Prefer retrieval-led reasoning. Read local doc files before answering framework-specific questions.

## Project Context
- **Project**: [Name and brief purpose]
- **Tech Stack**: [Key technologies]
- **Architecture**: [Monolith/Microservices/Monorepo/etc.]

## Critical Rules
- [Rule 1: Focus on "don'ts" and constraints]
- [Rule 2: Project-specific conventions]
- [Rule 3: Common mistakes to avoid]

## Commands
- **Build**: `[command]`
- **Test**: `[command]`
- **Lint**: `[command]`

## Documentation Index
> Read files from this index when relevant to your task.
[Root]: ./.docs/
[category]: {file1.md, file2.md}

## File-Specific Notes
- **[pattern]**: [convention or note]

3. Write Critical Rules

Focus on constraints and gotchas:

• What NOT to do (more useful than obvious "do's")
• Project-specific conventions that differ from defaults
• Common mistakes agents make in this codebase
• Security considerations (what not to commit, etc.)

Example rules:

## Critical Rules
- Never use `any` type in TypeScript—use `unknown` and narrow
- Always use `server-only` import for server utilities
- Run `pnpm check` before committing—it runs lint + typecheck + test
- Don't modify files in `generated/`—they're auto-generated

4. Add Compressed Documentation Index (if applicable)

For projects with extensive documentation (frameworks, large codebases):

1. Store docs in a .docs/ folder (or reference existing docs location)
2. Create a compressed index mapping categories to files
3. Add the retrieval instruction

Format:

## Documentation Index
> Agents: Read the file at the path below if related to your task.

[Root]: ./.docs/
01-getting-started: {installation.md, project-structure.md}
02-api: {endpoints.md, authentication.md, error-handling.md}
03-database: {schema.md, migrations.md, queries.md}

5. Interoperability

Recommend symlinking to support multiple tools:

# Create symlinks for other AI tools
ln -s AGENTS.md CLAUDE.md

Note: Only recommend symlinks the user has tools for. Common conventions:

• CLAUDE.md - Claude Code
• .cursorrules - Cursor
• COPILOT.md - GitHub Copilot

Anti-Patterns

• DON'T dump entire documentation files—link to them instead
• DON'T state obvious rules ("write clean code")
• DON'T duplicate README content verbatim
• DON'T include frequently-changing information (versions, etc.)
• DON'T add action workflows—those belong in Skills

Examples

Minimal AGENTS.md (small project)

# AGENTS.md

## Project Context
- **Project**: Personal blog built with Astro
- **Stack**: Astro, TypeScript, Tailwind CSS, MDX

## Rules
- Content lives in `src/content/`—follow the existing frontmatter schema
- Don't modify `src/components/ui/`—they're from shadcn

## Commands
- **Dev**: `pnpm dev`
- **Build**: `pnpm build`

With Documentation Index (framework project)

# AGENTS.md

> IMPORTANT: Read local doc files before answering framework questions.

## Project Context
- **Project**: E-commerce platform
- **Stack**: Next.js 15, TypeScript, Prisma, PostgreSQL
- **Architecture**: Monorepo with apps/ and packages/

## Documentation Index
[Root]: ./docs/