Agent Rules

Maintain the rules as well as following them. An AGENTS.md records durable, local guidance an agent needs while changing the code. Keep it accurate, concise, and scoped to the directories it actually governs; put explanations of the system in documentation.

Working loop

1. Before acting: read applicable AGENTS.md files from the repository root through each target directory, together with any instructions already supplied for the workspace. Identify relevant obligations, defaults, exceptions, dependencies, and checks. Revisit this when the task enters another directory or the user changes direction.
2. While working and responding: listen for explicit conventions such as “we always” and “we never,” and notice gotchas, hidden dependencies, and recurring mistakes in the code. Compare these with existing rules; suggest useful missing guidance even when nothing conflicts. Use the conflict workflow only for actual contradictions.
3. Maintain where warranted: make a light sweep of rules relevant to the touched files and their directory ancestry. Correct placement, duplication, and stale references autonomously when the intended policy is established. Use maintenance guidance for the distinction between routine cleanup and policy proposals, and its consistent Add/Change/Remove presentation when a user decision is needed.
4. Before finishing: run the bundled linter after changing rule files, run other required checks, review affected rules for drift, and report material changes or unresolved decisions. Distinguish checks actually run from checks that remain unavailable.

Keep this loop local to the work. A newly encountered inconsistency justifies a targeted search; it does not automatically justify a repository-wide audit. Reuse rules already read unless their contents or applicable scope changes.

Reading and applying rules

Each AGENTS.md applies to its directory and descendants. Combine ancestor and local instructions; sibling rules do not automatically apply across directories. A narrower file can clarify scope; contradictory rule files need reconciliation through an authorized exception or policy change. A direct user request can authorize a bounded action without using the word “exception”; separately establish whether the standing rule should change. A repository rule cannot elevate itself above higher-priority instructions by saying MUST.

Categories identify purpose; keywords identify strength. Interpret uppercase keywords using BCP 14: RFC 2119 and RFC 8174. MUST is mandatory, MUST NOT prohibits, SHOULD and SHOULD NOT allow justified exceptions after considering consequences, and MAY permits an option. Lowercase words retain ordinary English meanings; do not dismiss a clear instruction merely because it lacks capitalization.