AGENTS.md Starter Kit for Repositories

Start with one root file that describes repository-wide truth. State the repository purpose, primary applications or packages, source-of-truth directories, generated outputs, and boundaries that apply everywhere. If a subdirectory has materially different build commands, ownership, data sensitivity, or deployment rules, add a nested instruction file there and explain that it refines the root guidance for that subtree. Avoid copying the whole root file into every package; duplication creates contradictory instructions after the next change. [AR7][AR12]

Describe precedence plainly because different coding tools may discover custom instructions differently. Tell contributors to read the nearest applicable repository instructions and any named product documentation before editing. Keep critical safety constraints in enforcement as well as prose: branch protections, required reviews, CI checks, secret scanning, and provider permissions. An instruction file informs behavior; it does not technically prevent a command or an unauthorized merge. [AR7][AR9][AR10][AR12]

The opening should let an unfamiliar contributor form an accurate map quickly. Name the product, the runtime entry points, the main frameworks, and the directories most likely to change. Explain whether the repository is a monorepo and which directory is the actual application root for commands. Identify the production deployment source and default branch without including tokens or private infrastructure details. Link to the README or architecture record for deeper history rather than repeating it. [AR7][AR12]

Include a small tree only when it communicates ownership or flow. Annotate entries such as app for routes, lib for domain behavior, components for shared UI, content for editorial source, generated for never-edit output, migrations for reviewed database changes, and tests for verification. Remove entries that are obvious or unstable. The orientation is successful when a contributor can explain where a requested change belongs and which output should not be edited by hand. [AR7]

Write commands that can be copied from a clean checkout. Pin the package manager and runtime through repository configuration where possible, then mirror that truth in the instruction. State whether installation runs code generation or other scripts. Explain which environment file is an example and where developers obtain real values through approved channels. Never paste credentials into AGENTS.md. If local development can run with stubs or optional integrations, say which features will be unavailable and how failure should appear. [AR7][AR10]

Call out commands with side effects. A build that invokes a migration helper, an end-to-end suite that sends email, or a development seed that wipes a database must not look like an ordinary read-only check. Label local, preview, staging, and production targets. Prefer a safe verification command that does not require provider credentials. When external access is necessary, name the human approval or environment boundary rather than encouraging the agent to improvise. [AR7][AR9]

Give contributors the fastest relevant proof first, then broader gates. A useful ladder might contain one focused unit test, the package test suite, lint, typecheck, production build, and a targeted browser smoke test. Provide exact commands and explain when each is required. If tests depend on generated types or a local service, include that prerequisite. The ladder should match continuous integration so local success predicts review success. [AR7][AR9]

Define what the tests cover and what they do not. A green static content verifier may prove inventory, links, schema, and sitemap construction but not visual layout or production routing. A component test may prove validation but not a real payment provider. A build proves compilation, not successful activation. Ask for evidence proportional to risk and preserve manual checks for accessibility, visual behavior, and external integration boundaries. Never describe a passing narrow test as proof of the whole product. [AR3][AR7][AR9]

Tell agents to inspect the worktree before editing and preserve unrelated user changes. Name generated files and the command that owns them. Explain whether formatting is repository-wide or scoped. Forbid destructive cleanup commands unless a human explicitly authorizes them. State the branch naming and commit expectations, including whether changes should remain local. If deployments flow through a Git integration, record that workflow and prohibit ad hoc project creation or direct provider mutation. [AR7][AR9]

Identify high-risk paths such as migrations, billing, authentication, authorization, infrastructure, legal copy, and security policy. High risk does not always mean never edit; it means require named evidence and review. For database work, distinguish generating a migration file from applying it. For provider work, distinguish reading configuration from changing production. These boundaries help an agent continue useful local work while stopping at the real authority gate. [AR7][AR10]

A compact architecture section should answer how a user action becomes a result. Name the route or entry point, domain module, persistence or provider boundary, and event or UI output. For an API, link the OpenAPI document when it matches production. For content, name the registry that generates pages, schema, sitemap, and RSS. For analytics, name the client and server event layers and the canonical activation event. This change-path framing is more actionable than an exhaustive list of libraries. [AR6][AR7]

Record important invariants beside the path: authentication before data access, authorization by target, idempotency for retried writes, canonical host construction, UTC or local date assumptions, and source attribution preservation. Link to deeper decisions or diagrams. Keep the section current by reviewing it when a new subsystem or provider is introduced. If the architecture cannot be summarized without caveats, name the uncertainty rather than giving an agent false confidence. [AR6][AR7][AR8]

Say where secrets belong, which files are examples, and which values may be exposed to the client. Require server-side authorization for consequential routes and validation at trust boundaries. Remind contributors that page content and model output are untrusted inputs. Prohibit logging access tokens, passwords, complete sensitive payloads, or personal data merely to debug. Link repository secret scanning and incident instructions, including rotation when a credential is exposed. [AR7][AR8][AR10]

Name the safe fixtures for tests. Synthetic accounts and sandbox providers should be preferred over production records. State retention and deletion expectations for generated artifacts, traces, and screenshots that may contain user content. If a repository contains code with legal or compliance impact, require review by the named owner without presenting the instruction file as legal advice. A security section is useful when it turns broad caution into concrete checks and escalation boundaries. [AR7][AR10]

A completion section should list the user-visible outcome, tests run, build result, manual checks, changed files, and remaining limitations. Require the contributor to distinguish passed, skipped, and blocked checks. A command name without output or exit status is weak evidence. A screenshot without the tested URL and state is weak evidence. Keep the packet concise enough for review while preserving the exact failure or success boundary. [AR7][AR9]

For a web change, include canonical route and content-type checks when relevant, plus a production-like preview task. For a repository-only change, include the focused test, lint or typecheck, build, and any generated diff. For a security change, add negative tests and review notes. Do not ask the agent to claim production deployment, indexation, or provider state from local success. Those remain separate release steps with their own evidence. [AR7][AR9]

Move tutorials and historical context to durable documentation and link them by purpose. Keep commands, constraints, and decision boundaries close to the repository. Replace long prose with tested scripts where appropriate: one verify command can run content, type, lint, unit, and build checks while preserving their individual output. Do not hide destructive side effects behind a friendly aggregate command. The instruction should say exactly what verify runs and whether it is safe locally. [AR7][AR9][AR12]

Review the file when package scripts, runtime versions, deployment roots, provider flows, ownership, or security policy changes. A stale exact command is more harmful than a missing optional recommendation. Add a last-reviewed date only when the content is actually checked. Use pull-request review to confirm the instruction change accompanies the code change that made it necessary. [AR7][AR9]

Use these headings: Repository purpose; Scope and instruction precedence; Quick map; Runtime and package manager; Setup; Safe local development; Verification ladder; Editing and generated-file rules; Architecture and invariants; Security and privacy; Deployment boundary; Definition of done; and Escalation. Under each heading, replace examples with repository truth. Remove sections that do not apply rather than filling them with generic advice. Add nested instructions only after the root file works for a real task. [AR7][AR12]

Test the draft with one representative change. Give a contributor or coding agent only the task and repository access. Observe where it guesses a command, edits the wrong source, misunderstands a boundary, or cannot prove completion. Update the instruction to prevent the failure class without scripting the exact solution. Then run secret scanning, CI, and the repository's verification ladder. The best starter kit becomes shorter and more precise as repeated evidence reveals which guidance is truly necessary. [AR9][AR10][AR12]