generate-AGENTS-file

Generate AGENTS.md

Creates or updates AGENTS.md - a universal project context file for AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.).

Purpose: Prevent mistakes by providing context the AI would otherwise lack.

What belongs in AGENTS.md:

• Domain knowledge that isn't obvious from code structure
• Constraints that cause silent failures if violated
• Architectural decisions that affect how code should be written
• References to detailed rules via @ imports

What does NOT belong:

• Commands (LLMs know how to run pnpm, npm, pytest, etc.)
• Generic best practices (LLMs already know these)
• Project descriptions (that's what README is for)
• Anything an LLM would figure out from reading the code

The test: "Would an AI make a mistake without this specific piece of context?" If no, cut it.

Add an "Always Apply Rules" section at the top with @ references:

## Always Apply Rules

Core project rules that apply to all tasks:

@rules/git-interaction.mdc @rules/typescript-coding-standards.mdc

Why use @ references instead of extraction:

• AI coding assistants load the full rule when they see @path/to/rule.mdc
• Ensures rules stay up-to-date without AGENTS.md edits
• No token overhead from duplicating rule content
• Single source of truth for all conventions

When to still extract (rare):

• Only if a rule has a specific command or constraint worth highlighting elsewhere
• Don't duplicate - reference in "Always Apply Rules" section instead

From README.md:

• Project tech stack and versions (be specific: "Next.js 14" not just "Next.js")
• Key commands (dev, build, test)
• Skip: Project description, installation steps for end users, contributing guides

From .claude/context.md (if exists):

• Identity or personality instructions (if project uses custom personality)
• Any project-specific AI behavior guidelines

From recent git commits (last 10):

• Observe commit message style and conventions
• Identify patterns (emoji usage, conventional commits, etc.)

# Project Context for AI Assistants

## Always Apply Rules

Core project rules that apply to all tasks:

[@ references to your alwaysApply: true rules]

## Project Overview

Brief description of what this project is.

## Tech Stack

- Framework/language with specific versions
- Key dependencies that affect how code should be written
- Build tools and their commands

## Project Structure

- `dir/` - Brief purpose (only if non-obvious)
- Focus on where AI should look for specific types of files

## Code Conventions

DO:

- Specific patterns to follow
- Required practices unique to this project
- Non-obvious constraints that prevent mistakes

DON'T:

- Specific anti-patterns to avoid
- Project-specific constraints
- Explicitly forbidden practices (like --no-verify if that's a rule)

## Git Workflow

- Commit message format (if specific convention exists)
- Important: Include critical git constraints from always-apply rules
- Skip generic emoji lists - one example is enough
- Skip restating the full commit format if it's standard

## Important Notes

- Non-obvious gotchas or warnings
- Critical context that prevents mistakes
- Dependencies between systems
- Unique aspects of this project that AI must understand