Give Autobuild Repository Context

Give Autobuild the context your repository already has

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/                 # Loadable specialist procedures
│   └── db-migrations/
│       └── SKILL.md
├── review/                 # Repository-specific review guidance
│   └── overlay.md
└── runbooks/               # Task-specific operational procedures
    └── staging-checks.md

You do not need the whole directory on day one. Add only the files that resolve a recurring question or prevent a known failure.

Add this	Put this information there	How Autobuild uses it
.obvious/obvious.md	A concise orientation for Autobuild: important project context, required practices, and routing guidance for code workers	Injects this repository guidance into relevant code-worker context
.obvious/config.yml or .yaml	Workflow policy such as default branch, merge approach, preview information, QA paths, or generated-file commands	Turns supported values into effective workflow guidance and command inputs
.obvious/skills/	Repeatable specialist procedures, such as database migration steps or local verification workflows	Discovers repo skills and makes them available to load when a task needs them
.obvious/review/	Repository-specific review standards, high-scrutiny areas, scoring guidance, and noisy findings to suppress	Augments the code-review rubric for your repository
.obvious/runbooks/	Procedures for deployment checks, incident investigation, environment verification, or other focused operations	Gives agents reference material to consult for relevant tasks

This division keeps the repository legible. A developer working in an app directory can find the engineering rules that govern that code. An Autobuild task can find operating context without turning every local instruction into automation policy.

Start with guidance that prevents the next mistake

Begin with a root AGENTS.md. Name the commands an agent should run before handing work back, the architectural constraints it must preserve, and any directories that contain more specific instructions. Add nested AGENTS.md files only where local rules meaningfully differ from the root guidance.

Next, create .obvious/obvious.md if there is short, stable orientation that you want Autobuild code workers to carry into relevant work. Keep it focused: the repository's purpose, key boundaries, and where to look for more detail are more useful than a copy of every internal document.

If your team also has explicit workflow choices, a small configuration file is enough to begin:

branches:
  defaultBase: main

pr:
  merge:
    method: squash

Add .obvious/config.yml when an agent should not guess those choices, such as the base branch, merge approach, preview convention, QA path, or required generated-file command. Add a skill when a repeated procedure has enough steps or domain knowledge to deserve its own guide. Add review guidance when generic review does not capture your high-risk paths or established standards. Add runbooks when an operational procedure is relevant only for certain tasks.

A small first setup often looks like this:

AGENTS.md
.obvious/
├── obvious.md
└── config.yml

That is enough to separate code-working rules, short Autobuild orientation, and workflow policy. Expand it as your tasks expose repeated needs.

Keep context accurate and safe

Repository context shapes how an agent approaches work. Treat it like code: keep it concise, review changes, and remove instructions that no longer match your system.

Autobuild loads .obvious/obvious.md from your default branch when injecting that guidance into relevant code-worker context. Repository skills in .obvious/skills/ are also discovered from the default branch and loaded only when relevant. This prevents an unmerged branch change from silently introducing injected guidance or a loadable skill into active work.

Configuration has a different responsibility. Values in .obvious/config.yml or .yaml become effective workflow guidance for the active repository, but they cannot weaken platform safeguards, permissions, branch protection, or required completion gates. Use configuration to express how your team works, not to bypass protections.

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.