Skip to main content
AGENTS.md is a scoped runtime bootstrap contract. It gives an agent the minimum high-value context needed to understand its environment, make correct decisions, follow constraints, use the right workflows, and discover sources that would otherwise be easy to miss. It is not comprehensive documentation, a catalog of everything in the repository, or a guide for maintaining AGENTS.md itself.

​
Decide what belongs inline

Add content when at least one of these tests is met:
  • It has demonstrated behavioral value, or its absence has caused observable mistakes or wasted work.
  • It defines a historically misunderstood or rare but high-consequence boundary.
  • It provides durable company, product, customer, system, or operating context that changes which otherwise valid decision is best.
  • It routes work correctly or reveals a valuable tool, workflow, entrypoint, or source an agent may not discover on its own.
“Important information” alone is not an inclusion test. For each candidate, weigh its value against both its direct cost and the context inherited by every nested scope. Account for duplication, staleness, maintenance burden, and the risk that an agent will apply the instruction too broadly or rigidly. Evaluate both the harm of omission and the harm of over-application. Tune instructions to observed behavior rather than accumulating generic best practices. One low-consequence mistake rarely justifies another permanent rule; a recurring or high-consequence failure may.

​
Prefer enforcement and progressive disclosure

Use the earliest reliable intervention. Prefer code structure, types, linting, formatting, tests, or CI when they can enforce an invariant effectively. Keep a concise instruction when enforcement is late, partial, expensive, unreliable, or unclear enough that an agent still needs guidance. Give detailed material one canonical home. When useful content is too large for runtime context:
  1. Move it to the appropriate specification, runbook, or reference.
  2. Keep the decision-critical summary or trigger inline.
  3. Link directly to the canonical source and explain when and why to read it.
Do not replace critical runtime instructions with bare links, and do not delete helpful authoritative material solely to make AGENTS.md shorter.

​
Orient decisions before implementation

State concise, durable context that changes tradeoffs: what the company or product does, who it serves, the role of this system, and any resource or operating priors that materially affect the best solution. Link to canonical sources for the extended context instead of making agents reconstruct purpose from low-level code. Keep current work, detailed customer evidence, ownership, versions, migration state, and other mutable facts in live or regularly reviewed sources whenever a pointer provides enough runtime value. If a mutable fact must remain inline, keep it brief and link to its authority. Avoid unanchored terms such as “currently,” “recently,” “new,” or “legacy for now”; use an absolute date or a live source.

​
Layer instructions by scope

  • The root AGENTS.md contains only repository-wide context, rules, defaults, and discovery.
  • A nested AGENTS.md contains only subtree-specific additions, qualifications, explicit overrides, and local discovery.
  • Do not repeat parent wording. Review the combined parent and nested context, not each file in isolation.
  • State scope and precedence briefly when they are not obvious. Make overrides explicit instead of requiring the agent to infer them.
Curate high-value tools, workflows, real entrypoints, and source-of-truth files rather than listing the repository landscape. A path appearing in source code, ls, or package.json does not explain its authority or when to use it. For every non-obvious link, say what it contains, when to open it, and why it matters. Phrase links as an explicit condition, canonical target, and reason to read it. Link to the most specific canonical target. Verify that it contains the promised information, is accessible, is current or explicitly dated, and is written for the person or agent making the decision.

​
Write for retrieval and correct application

After a minimal scope statement, order content in the sequence an agent needs to decide and act. Put the most consequential mental models, boundaries, and guardrails first; follow with workflows, verification, conventions, and delivery guidance as needed for the scope.
  • Use operational, grepable headings and canonical terminology.
  • Keep related instructions together and near the workflow that triggers them.
  • Use short prose for coherent orientation and one-idea bullets for independent rules, references, and actions.
  • Use must, never, always, and only for invariants; prefer or default to for heuristics; and before or when for conditions.
  • State real exceptions and scope boundaries. Give every prohibition a safe alternative, a source to consult, or a condition for requesting judgment.
  • Name exact commands, paths, tools, and concepts. Keep broadly applicable verification commands inline; link to uncommon variants and troubleshooting.
  • Keep concise terminology distinctions that change decisions or have been repeatedly misunderstood. Link to comprehensive glossaries, inventories, data models, and architecture references.
Avoid teaching examples, exhaustive inventories, motivational rhetoric, and task-specific checklists unless they independently pass the inclusion test.

​
Keep authoring governance outside runtime files

Runtime content tells agents how to operate in the repository. The process for authoring, evaluating, and maintaining that content belongs in an external policy or review workflow. Do not paste meta-instructions such as “keep this file short,” “avoid duplication,” “maintain AGENTS.md,” or “update this file when behavior changes” into runtime files. Size is a review signal, not the objective; retrieval and correct behavior are the objective. Use interaction audits, repeated corrections, incidents, rejected changes, support patterns, and representative evaluations as evidence. When a failure occurs, decide whether the best fix is clearer code, types, enforcement, tooling, canonical documentation, discovery guidance, or a runtime instruction.

​
Review and refactor safely

Before revising an instruction file:
  1. Inventory the applicable root and nested files, then resolve the inherited instruction chain.
  2. Read the complete target, parent instructions, linked canonical sources, and relevant evidence.
  3. Measure the target and inherited context, then classify each block as keep, compress, move and link, delete, or replace with mechanical enforcement.
  4. Review exact proposed wording, including interactions, misleading implications, and over-application risk.
  5. Reread the complete result and validate formatting, links, duplication, scope, retrieval, and representative agent behavior.
Review linked guidance when an important target moves or changes. Do not assume a rule became obsolete merely because its targeted failure stopped; first determine whether the risk disappeared, enforcement replaced it, or the rule is preventing it.

​
Charlie-specific instruction loading

Charlie loads shared AGENTS.md and CLAUDE.md instructions at any directory depth. Charlie-specific CHARLIE.md instructions load only at the repository root or anywhere beneath the root .agents/ directory. CHARLIE.md is ordinary repository content, not a confidentiality, authorization, or access boundary. See Customization for the supported instruction, skill, and daemon surfaces.

​
Source and ownership

This page is Charlie Labs’ stable public representation and public guidance for AGENTS.md authoring. Charlie Labs maintains the detailed canonical strategy internally as the maintenance authority.