> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlielabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS.md instructions

> Design concise, scoped runtime instructions that improve agent decisions and discovery.

`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.

## Make links useful at decision time

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](/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.

## Related docs

* [Customization](/customization)
* [Skills](/skills)
* [How it works](/how-it-works)