Agent instructions

Actively maintained production repositories¹ must work with Claude Code, Codex, Cursor, and OpenCode. Each approved coding agent must receive the same repository rules, commands, boundaries, and stop conditions.

This standard applies to coding agents working in repositories. It does not govern any AI product features. An editor/IDE, such as Visual Studio or Visual Studio Code, is separate from a coding agent. Engineers may, for example, use either editor while running an approved terminal agent, like claude or opencode which have IDE support built-in.

What ready means

A repository is considered “AI-ready” when each approved agent can:

• find the effective instructions for any file it may change;
• identify the owning team and the relevant part of the repository;
• prepare a working development environment from the repository root;
• run the correct focused and full checks without interactive input;
• identify generated, vendored, migration, restricted, and prohibited areas;
• find branch-specific detail when a task requires it; and
• stop for human approval before an action crosses a stated boundary.

The engineering standard owns the required structure and shared rules, but each repository owner owns local accuracy. Repository instructions may add constraints, but they must not weaken an organization-wide requirement.

Scope and adoption

This standard covers actively maintained repositories used to build, deploy, operate, or configure production systems. Until the organization settles the location of repository metadata in GitHub issue 26, the owning team decides whether a repository is covered. Missing metadata does not defer compliance.

New production repositories must comply when created. Existing covered repositories comply within 90 calendar days after this standard is adopted. They comply sooner when a change alters the development, build, or test workflow.

Approved agents

The approved coding agents are:

Changing the approved list requires an ADR with Engineering Navigator review, in addition to security and legal review from Payward. The review must cover instruction compatibility, company-managed account support, provider configuration, data handling, retention, and auditability.

Required files

Every covered repository has these files at its root:

AGENTS.md
CLAUDE.md

AGENTS.md is the canonical instruction file. CLAUDE.md contains exactly this import and no other text:

@AGENTS.md

Every nested AGENTS.md has an adjacent CLAUDE.md with the same exact import. Add a nested AGENTS.md only when a package or subtree has materially different commands, boundaries, or change rules. The root instructions still apply.

Do not repeat repository instructions in other tool-specific rule files. Settings, hooks, MCP configuration, and reusable skills are allowed when another standard permits them, but they must not restate or override AGENTS.md.

Required structure

Every root AGENTS.md uses these headings in this order:

1. Purpose and ownership
2. Repository map
3. Setup
4. Commands
5. Architecture and boundaries
6. Change rules
7. Security and approvals
8. Documentation and handoff
9. Known traps
10. Stop conditions

Extra headings are allowed after the required headings. Consult the standards provides an Engineering standards section that points agents at this site. Nested instructions use the same structure but may omit a section that the root file fully covers. They must not contradict the root file.

The root file directly states the repository purpose and owner, repository or package map, setup prerequisites, exact commands, architectural boundaries, security and approval rules, known failure modes, and stop conditions. It also links to CODEOWNERS.

Detailed architecture, style guides, runbooks, and pull request guidance may live in checked-in files. A pointer (or @ mention) names the material and tells the agent when to read it. For example: When changing request authentication, read @docs/authentication.md before editing. External links are supplemental and may not carry a required repository instruction.

Root instruction template

Replace every angle-bracketed value. Remove an example that does not apply rather than leaving a placeholder.

# <repository name>

## Purpose and ownership

<One sentence stating what this repository produces or operates.>

- Owning team: <team name and contact>
- Ownership rules: [CODEOWNERS](.github/CODEOWNERS)

## Repository map

- `<path>`: <what lives here and why an agent would change it>
- `<path>`: <what lives here and why an agent would change it>

When changing <subsystem>, read [<document name>](<relative path>) before editing.

## Setup

Prerequisites: <tools and exact supported versions>.

From the repository root:

1. Run `<dependency or bootstrap command>`.
2. Run `<local configuration command>`.
3. Run `<setup verification command>`.

Setup is complete when `<verification command>` exits zero and <observable result>.

## Commands

Run these commands from the repository root. They do not prompt for input and return a nonzero exit code with useful failure output.

| Outcome | Command | Done when |
| --- | --- | --- |
| Format changed files | `<format command>` | The command exits zero and leaves no formatting diff. |
| Lint | `<lint command>` | The command exits zero. |
| Type-check | `<type-check command>` | The command exits zero. |
| Run focused tests | `<focused test command and selection syntax>` | The selected tests pass. |
| Run the full test suite | `<full test command>` | The suite exits zero. |
| Build | `<build command>` | The expected artifact exists and the command exits zero. |

## Architecture and boundaries

- <Boundary that must remain true, with the reason.>
- <Direction of allowed dependencies.>
- Generated files: `<paths>`. Change their source and run `<generator command>`.
- Migrations: `<paths and ordering rule>`.
- Vendored code: `<paths and update process>`.
- Prohibited changes: `<paths or resources an agent must not edit>`.

When changing <architecture branch>, read [<design document>](<relative path>) before editing.

## Change rules

- Keep changes within the requested outcome.
- Add or update tests for changed behavior.
- Update instructions in the same pull request when this repository's setup, commands, layout, boundaries, owner, or approval rules change.
- An agent may edit files and run validation needed for the requested task. It may commit, push, open a pull request, publish, deploy, or change external state only when the request explicitly names that action and its target.

## Security and approvals

- Use company-managed accounts and approved provider configurations.
- Use `<approved local fixture or test environment>` for development and tests.
- Store secret values in `<approved secret system>` and refer to them by name only.
- Obtain approval from `<role or team>` before <repository-specific sensitive action>.

When changing authentication, authorization, encryption, or data classification, read [<security document>](<relative path>) before editing.

## Documentation and handoff

- Update `<README, runbook, API reference, or changelog paths>` when their behavior changes.
- Follow [pull request guidance](<relative path>) for required context, ticket links, and review.
- Record what was validated and what remains unverified.
- Do not add generated-by notices, tool attribution, or AI co-author trailers to commits or pull requests.

## Known traps

- `<specific command or file>` fails when <condition>. Use `<recovery>`.
- `<similar-looking path>` is not used by <runtime or build>. Change `<correct path>`.

## Stop conditions

Stop and ask the repository maintainer before:

- accessing, exposing, copying, or rotating a secret;
- writing to production or shared infrastructure;
- deploying, publishing, pushing, or changing another external system;
- running a destructive filesystem, database, cloud, or Git operation;
- adding or changing a production dependency;
- changing authentication, authorization, encryption, or data classification;
- proceeding when requirements or applicable instructions conflict or remain unclear.

Command requirements

Root commands run from the repository root. They are non-interactive, return meaningful exit codes, and print enough failure context for a maintainer or coding agent to act. Provide options for both a focused test command, and the full repository check. For example: npm test or npm test -- file.tsx. Nested instructions may add narrower commands for their subtree.

Do not document a command that only works through shell history, an untracked file, a personal alias, or a maintainer’s local state.

Size and instruction chains

Review any instruction file longer than 200 lines and move branch-specific detail into checked-in references or nested instruction pairs. Keep the combined effective instruction chain for every repository path at or below 32 KiB. The shared check treats a larger chain as an error.

Do not split information that an agent always needs. Keep a rule beside its reason, exceptions, and completion criteria. Use a nested pair or a conditional pointer only for detail that applies to a specific part of the repository or type of change.

Enforcement

Each covered repository calls the organization-owned agent-instructions action from NT-NinjaTrader/gh-actions in its pull request workflow. The action is a required branch protection check. Repositories do not maintain local variants of the validator.

The shared action checks that:

• the root AGENTS.md and exact CLAUDE.md import exist;
• every nested instruction file has its adjacent pair and no orphan CLAUDE.md exists;
• the required root headings exist in the approved order;
• required direct sections are not empty and copied placeholders are gone;
• required relative pointers resolve to checked-in files;
• competing tool-specific repository instruction files are absent;
• files over 200 lines produce a review warning; and
• no effective instruction chain exceeds 32 KiB.

The action verifies structure, not truth. Maintainers verify local accuracy when adopting the files and at least quarterly after adoption.

Keeping instructions current

Update AGENTS.md in the same pull request that changes repository ownership, layout, setup, commands, architecture boundaries, or approval rules. Update the adjacent CLAUDE.md only when repairing its exact import.

The owning team reviews the effective instruction chain at least quarterly. CODEOWNERS assigns reviewers for root and nested instruction files. Local additions may be stricter than this standard. Any exception that weakens a requirement follows the exceptions process.

References

• AGENTS.md Standard
• Claude Code: Memory
• Codex: Custom instructions with AGENTS.md
• Cursor: Rules and AGENTS.md
• OpenCode: Rules