agent-instructions

Agent instructions

Create the smallest set of instruction files that helps the requested coding agent work safely and accurately in this repository. Recover facts from the repository before asking questions, and distinguish commands you executed from commands you only found in documentation.

Choose the task and target

Determine whether the request is to:

• create instructions where none exist;
• improve one existing file;
• reconcile duplicated or conflicting instruction files;
• add scoped instructions for a package or subtree; or
• translate shared repository facts for more than one agent runtime.

Infer the target from the request and existing conventions. Ask only when the choice changes installation scope or runtime behavior. Do not create parallel vendor files unless the user asks for them.

Use the target's native form:

• AGENTS.md for agents that follow directory-scoped AGENTS instructions;
• CLAUDE.md for Claude Code project memory;
• .cursor/rules/*.mdc or the repository's existing Cursor convention;
• nested files only when a subtree needs meaningfully different commands, ownership, or boundaries.

Inventory instruction scope

Before writing, locate all existing agent instructions and relevant repository guidance:

pwd
rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g '.cursor/**' -g 'README*' -g 'CONTRIBUTING*' -g 'Makefile' -g 'justfile' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'

For each instruction file, record its directory, intended runtime, inherited scope, and any statements that conflict with a nearer file or repository evidence. Respect the nearest scoped instruction. Do not duplicate root guidance in every nested file.

Preserve valid project-specific constraints. Remove stale facts and redundant prose only when the replacement retains their intent.

Build an evidence map

Read the minimum repository evidence needed to establish:

• project purpose, language, framework, and runtime versions;
• package or workspace boundaries;
• install, development, build, lint, typecheck, test, and release commands;
• entry points and locations of domain logic;
• generated files, migrations, credentials, deployment configuration, and other high-risk areas;
• naming, testing, formatting, and architectural conventions visible in representative code;
• required services, environment variables, ports, and setup order.