Give Autobuild Repository Context

Autobuild can work without repository guidance, but then it must infer your conventions from code, tests, and tooling. That creates avoidable work and avoidable risk: the agent may discover the right test command late, miss a directory-specific constraint, or apply a sensible pattern that does not match your team's rules.

Give Autobuild two kinds of context instead. Put code-local working guidance in AGENTS.md. Put Autobuild-specific operating guidance in .obvious. Used together, they help agents make changes that fit your codebase while following the workflow and review practices you choose for automated work.

Both layers are optional. Start with the smallest guidance that prevents a real mistake, then add structure only when your team has a repeated need.

Use AGENTS.md for rules that belong with the code

AGENTS.md is a human-readable instruction file for how an agent should work in your repository. A root AGENTS.md is the right home for rules that apply across the repository: commands that prove a change is safe, architectural boundaries that must not be crossed, key source-of-truth documents, and conventions that are easy to violate by inspection alone.

When one area of the repository needs narrower rules, add an AGENTS.md in that directory. For example, an API directory might require a migration workflow, while a UI package might define its component and testing patterns. Keeping those instructions near the affected code makes them easier for your team to maintain and more precise for an agent making a focused change.

Autobuild agents are instructed to read applicable AGENTS.md guidance when researching affected areas, implementing changes, and reviewing code. That is different from treating every instruction file as universal context in every interaction: write each file for the work performed in its scope.

Use .obvious for how Autobuild should operate

.obvious complements AGENTS.md; it does not replace it. Use it for the guidance, policy, and reusable procedures that are specific to running Autobuild around your repository. A complete setup might eventually look like this:

.obvious/
├── obvious.md              # Short Autobuild orientation
├── config.yml              # Repository workflow policy
├── skills/                 # Checked-in skills for this repo
└── runbooks/               # Operational procedures for recurring work

obvious.md is a short orientation: what the repository does, who uses it, and the highest-priority constraints for automated work. config.yml sets workflow policy — which branches Autobuild can target, what approvals it should request, and similar operating rules. The skills/ and runbooks/ directories let you check in reusable agent procedures alongside the code they support.

Start with guidance that prevents the next mistake

The most effective first AGENTS.md is not comprehensive — it prevents the specific mistake you expect. If your test suite requires a specific command, write that. If a directory should never be modified by an agent working on another area, write that boundary. A file with three clear rules is more useful than a file with thirty vague ones.

The same principle applies to .obvious. Start with obvious.md and the one or two rules in config.yml that would otherwise require manual correction on every pull request. Add skills and runbooks when a repeated task is worth packaging as a reusable procedure.

A small first setup often looks like this:

AGENTS.md           # Three rules: test command, off-limits directory, PR size guideline
.obvious/
└── obvious.md      # Two paragraphs: what the repo does, what automated work is appropriate

Keep context accurate and safe

Guidance that is out of date is worse than no guidance — it teaches the agent to make a specific kind of mistake with confidence. Treat AGENTS.md and .obvious like any other documentation: review them when the underlying practice changes, remove rules that no longer apply, and keep the scope of each file matched to the work it governs.

Runbooks are also scoped to need: agents consult relevant operational procedures when the task calls for them, rather than loading every runbook into every interaction.