An agent-ready environment lets a coding agent check its own work in the repository. Without one, the agent stops when its work looks done, you find the problems in review, and you become its test suite. This lesson is for engineers who want to understand what makes a repository checkable and learn to audit their own. You will score one pillar by hand before using the companion skill for a full audit.
Where to start has the audit skill's install command and the first steps for a new project.
When you ask a coding agent for a feature, it edits files and runs the checks it can. It stops when the work looks done. It cannot judge behavior it cannot observe.
The repository's checks let the agent test whether the work is done. With a type-check command and tests that cover the behavior, the agent can find and fix failures. With a running app and realistic data, it can also inspect the page.
Illustrative task “Add a due date to tasks.” The agent edits the code, the build passes, and it reports done. Four problems are hiding in the change.
Stores the due date as text where the form expects a date.
Without it
Nothing checks types. You spot it in review.
With one check command (pillar 2)
The type check fails, and the agent fixes it before it says done.
Marks tasks that are due today as overdue.
Without it
Nothing exercises the rule. A user reports it.
With tests with signal (pillar 3)
A test for the overdue rule fails, and the agent fixes the comparison.
Crashes the task page when a task has no due date.
Without it
The agent never opens the page. You find the crash when you try it.
With seeded app, one command (pillar 6)
The agent starts the app with seeded tasks, including one with no due date, and sees the crash.
Reads the .env file to borrow an API key for a quick test.
Without it
Nothing stops it, and nobody notices.
With deny rule on secrets (pillar 7)
The deny rule blocks the read, so the agent asks for a test key.
Figure 1. Who catches it? The same change, with and without four parts of an agent-ready environment. The scenario is illustrative.
Three jobs: tell, check, bound
An agent-ready environment has eight areas, called pillars. Each pillar does one of three jobs.
Tell
Give the agent information it cannot see in the repository, such as why it must not copy an old helper. Also give it the command that runs every check.
Check
Return a pass or fail result through a type checker, a test, or a health check after setup.
Bound
Limit what the agent can access or change, and name who approves the result. For example, deny access to .env files or require a person's authorization to merge.
In Figure 1, the check command, tests, and seeded app check the work. The deny rule limits the agent's actions. None of these four does the tell job. Instructions guide the agent's work but cannot verify the result.
Advisory or enforced
A rule reaches the agent on one of two channels. Advisory guidance is text in the prompt, AGENTS.md or CLAUDE.md, and skills. The agent reads it and may decide it does not apply. Enforced guidance uses hooks, deny rules, the sandbox, the type checker, linters, or required CI checks. Each mechanism runs at an action boundary, such as a tool call, commit, or merge, regardless of the agent's decision.
AdvisoryPrompt, AGENTS.md, skills
The agentWeighs the guidance and decides what to do
Enforced, at the boundaryHooks, deny rules, sandbox, type checker, required CI
The actionTool call, commit, or merge, or a block with a message
Figure 2. The agent can disregard advisory guidance. Enforced checks run between its decision and the action, regardless of that decision.
Put each rule on the channel that matches its exceptions.
Enforce rules that have no exceptions. When documentation does not make the agent follow a rule, implement it in code, as OpenAI's harness engineering article describes.
When the agent repeatedly misses an advisory line, check for two causes. If the rule has no exceptions, enforce it with a hook or deny rule. If the file's length makes the line hard to find, shorten the file. Emphasis fixes neither cause.
Keep preferences advisory. A large enforced set is a sign that preferences have leaked into it. Hooks sometimes block valid actions, and someone must maintain them.
Write error messages that tell the agent how to fix the failure, so it can repair its own work.
Durable and decaying guidance
Some guidance compensates for model weaknesses. Other guidance provides information or tools the model cannot get by itself. Vendors now separate the two: Anthropic's Claude Code best practices include “What you can stop doing”. The first kind is decaying guidance: it loses value as models improve. The second kind is durable guidance. Invest in that kind.
Decaying: makes up for the model
Durable: gives the model what it cannot get
Emphasis, IMPORTANT, ALL CAPS
Facts that are not in the repository
“Think harder”, “keep going”, “don't be lazy”
A check that returns pass or fail
Architecture tours and file-layout descriptions
Deterministic enforcement of rules with no exceptions
Aggressive context management
A running, observable, seeded environment
Delegating to a subagent “for a better answer”
An independent reviewer that did not see the author's reasoning
The skill ranks a reproducible environment (pillar 6) as the most durable investment. Static and test gates come next because they make the work checkable. Documentation loses value as models get better at reading code.
The eight pillars
You can audit each pillar on its own. Each has a job (tell, check, or bound) and an observable audit check.
Figure 3. The eight pillars, grouped by the job each one does. Select a pillar to jump to it.
Pillar 1: Code shape
Tell
Agents learn conventions from the code and copy the patterns they find, including ones the team is replacing. With one pattern for each job, the nearest example is the right one to copy.
Audit check In three recent features, each decision is made in one place. Decisions include validation rules, permission checks, and state transitions. Duplication and boundary tools pass.
What good looks like
Each concept has one owning module. Other modules call it instead of implementing the same concept again.
Dependency direction is declared and enforced, for example with ESLint boundary rules, dependency-cruiser, or Fallow in TypeScript, import-linter in Python, internal/ packages in Go, or ArchUnit on the JVM.
Data enters at one validated boundary and flows one way through named layers.
Mark legacy areas “do not copy”. Where possible, enforce this with a lint rule that bans the old import.
The agent can read a build's exit code and a linter's results. The command that runs these checks is the most useful line in an instruction file. A Stop hook makes running the command a condition of finishing instead of a request. Codex guidance also asks for a “done when” condition and the relevant lint, format, and type checks.
Audit check One command runs every static gate locally, and CI runs the same command. Clean main is green, and suppressions are counted.
What good looks like
Strict typing: TypeScript strict, mypy or Pyright strict, go vet with staticcheck, Clippy with warnings denied.
Lint, dead code and unused dependencies, complexity limits, and duplication checks.
One check command runs locally and in CI with the same configuration. A changed-files mode keeps it fast.
Warnings fail the build or do not exist.
Each suppression carries a reason, and the total is tracked.
Tests are the main pass-or-fail check. Agents tend to call a feature complete after unit tests or a curl call. They catch more bugs when they test end to end as a user would. The agent runs and trusts every test, so a test that cannot fail gives false confidence.
Audit check A single test file runs with one command. A sample of tests each maps to one contract and one credible regression.
What good looks like
Each layer owns a different risk. Unit tests check pure logic. Component tests check one unit's public contract. Integration or contract tests check boundaries with real dependencies. A few end-to-end tests check user journeys.
Each contract has one primary test at the strongest boundary that reaches it.
A regression test fails on the code before the fix.
Tests are fast and deterministic, and coverage is measured on changed lines.
Mutation testing on critical modules proves the tests can fail.
Review flags deleted tests and weakened assertions.
Instruction files load into every session, so each line uses the agent's attention on every task. Keep the file short and load task-specific detail only when needed. For each line, ask two questions:
Could the agent find this by reading the code?
Would it actually go and look?
If both answers are yes, delete the line. Keep verification commands even though package.json contains them: they are the most useful lines. For global behavior rules that no repository can show, use the decay test.
Audit check Every always-loaded line passes the two-question test or the decay test, and every documented command runs.
What good looks like
In the file that always loads, keep commands for install, single test, typecheck, lint, and running the app. Describe misleading parts of the code, decisions the code does not show, and anything corrected twice.
Repeated procedures live in skills, which load only when a task needs them.
Decision records explain why. A glossary maps domain terms to code names where they differ.
CI runs the documented commands and checks the links.
No dated advice in the body. Version requirements that are still true stay.
Leave out layout descriptions: agents can find the layout easily, and descriptions become outdated quickly. A short pointer to an unusual layout is fine.
A reviewer in a fresh context has not seen the author's reasoning, so that reasoning cannot influence its review. Read-only tools prevent edits. A reviewer asked to find problems always finds some. Fixing every finding adds abstraction layers and tests for impossible cases. State what the reviewer should skip in the review prompt.
Audit check Each review angle has a trigger, runs read-only in a fresh context, and has its findings verified before anyone fixes them.
What good looks like
Leave anything a tool can check to a gate (pillar 2).
On every change, check that the diff meets the spec or ticket.
Run other review angles when the diff carries their risks. Check simplicity and reuse for a new abstraction or dependency. Check test value when tests change. Review security for authentication, input, secrets, or permissions. Review performance for hot paths and unbounded loops. Check coding standards for rules no linter can express.
The reviewer gets the spec and the diff, not the author's reasoning.
Each finding is checked against the code before anyone fixes it.
A person authorizes the merge, either each time or in advance under the scoped authorization in pillar 7.
The agent needs a running app and data that covers the states it must inspect. A fresh worktree has no installed dependencies, and installing them by trial and error is slow and can fail. A setup failure may not stop the agent: GitHub's Copilot documentation says it continues in a partial environment. End setup with a health check to detect these failures.
Audit check Inside the agent's sandbox, one command starts a seeded, healthy app from a fresh worktree. Two worktrees run at once without collisions.
What good looks like
One command starts a running, seeded app from a clean checkout, both in the agent's sandbox and on a workstation. Each worktree has isolated ports, databases, and profiles.
Script both cold setup (from nothing) and warm setup (dependencies already present). End setup with a health check that fails loudly.
A deterministic seed, versioned with the schema, covers the states that matter: empty, error, large, each permission level, each locale. It contains no production personal data.
The agent can observe the app: browser automation, logs, metrics, and traces from the command line.
Provide one teardown command and a preview environment for human reviewers on each pull request.
The recipe lives in a script or a project skill, not a README paragraph.
For a repository that ships guidance instead of an app, use a throwaway host home where the guidance applies. Add a harness that runs agents against it.
Before a run goes unattended, answer five questions:
Does it know what done looks like?
Can it check its own work?
What may it touch?
What stops it?
Where does the result go, and who signs off?
Rules that must never be broken belong in deny rules, hooks, or the sandbox. A model-based safety classifier makes a judgment call, and it can be wrong.
Audit check Every “never” rule is a deny rule, hook, or sandbox limit. Unattended runs have turn or spend caps and a named sign-off on the result.
What good looks like
Deny rules for secrets and protected paths.
Worktree or container isolation, and least-privilege tokens.
Turn or spend caps on unattended runs.
A person authorizes merges, deploys, and anything irreversible. They can authorize each action or give advance authorization with a stated scope, an enforced boundary, a run cap, and a named sign-off on the result. Missing authorization is a gap. Running without a repeated approval prompt is not a gap.
Anthropic's skill authoring guide recommends measuring the agent without guidance first. Then write the minimum guidance that addresses the failures you observed. Compare each revision with that baseline. Test with every model the guidance targets: an instruction one model needs may be redundant for another. Guidance that compensated for older models can become unnecessary.
Audit check Each instruction file or skill has evidence that it changes behavior against a no-guidance baseline.
What good looks like
Evaluations compare guidance with no guidance on matched tasks, model, and harness.
Routing evaluations check that skill descriptions trigger when they should.
Periodically remove instructions the current model already follows by default.
An audit turns the pillar checks into a score and a fix order. Learn the scoring rules first, then try one pillar in your own repository. The companion skill uses the same rubric for a full audit.
How a pillar is scored
Each pillar scores from 0 to 3, and each level builds on the one below it. Higher scores need stronger evidence.
0AbsentMissing, or no verified evidence.
1PresentA documented policy, a script, or a partly working mechanism, with some level 2 criterion unmet or unverified.
2RunnableThe pillar's audit check passes on runnable evidence. Only pillar 6 requires a fresh checkout.
3Enforced and measuredThat check also blocks the action it guards, and its results are tracked over at least 20 runs or 30 days.
Figure 4. The score ladder. A required check that blocks merge, or a hook that blocks a tool call, is enforced. Optional CI that fails loudly but does not block merge stays at level 2.
Give each pillar the highest score for which the verified evidence meets every requirement. List unverified checks under Unverified. They cannot raise the score.
Scoring rules for auditing without the skill
The skill applies these rules for you. Its SKILL.md holds the full rubric, and each pillar's reference file has its detailed checks.
For levels 2 and 3, the pillar must pass its audit check. Use the detailed reference checks to identify the top gap. They affect the score only where the reference says so.
When a pillar covers several artifacts, such as instruction files, score the weakest applicable artifact. If the audit check needs a missing artifact, the pillar stays below level 2. The missing artifact alone does not require a score of 0.
Mark a pillar N/A when it does not apply. Give a one-line reason and exclude it from the total. When only part applies, score that part and name the checks you omitted.
For pillar 7, count a rule as enforced when the host or forge reports it active. Examples include a ruleset read with gh api or the host's effective deny rules. A rule stated only in prose is level 1.
Score a failed fresh setup once, in pillar 6. Other pillars can reach level 2 using CI results for the exact commit audited. They can also use a local run with dependencies supplied another way, labelled as such.
Required checks, branch rules, and review history need read access to the forge API, such as gh api. Without that access, mark them unverified.
Evidence, from strongest to weakest:
A local run in a fresh checkout, inside the agent's sandbox. Record the sandbox configuration, so a failure can be traced to the repository or to the auditor's machine.
CI results on the exact commit audited.
CI results on current main, labelled as a different commit.
Source inspection: the script exists and reads correctly. For anything runnable, this supports level 1 at most.
Try it: score your static gates
Use one repository you work in. Your result will be a score for pillar 2, the evidence behind it, and one gap to fix.
Find the command that runs all static gates. Check the instruction file and the scripts it points to.
Run it on clean main. Record the commit, command, duration, and result.
Check that CI runs the same command with the same configuration. Count suppressions by kind: inline directives, disabled rules, and allowlist entries.
Compare your evidence with pillar 2's audit check and the score ladder in Figure 4. Choose the highest level whose requirements you have verified.
If you cannot read the CI results or required-check settings, list them under Unverified. They cannot raise your score. Write one top gap and a fix: for example, make an optional check required. Its channel is Enforced, because the proposed fix would block merge.
Choose the full audit's modes
An audit has three modes. Use every mode that applies. The new-project mode is under Where to start. A repository that ships guidance, such as Filip Stack, needs both the existing-repository and engineering-guidance modes.
Existing repository
Measure what is there before you change anything.
In the agent's sandbox, measure the time from a fresh worktree to a seeded, running app. Record cold and warm setup separately, including each manual step.
Run every gate on clean main. Record how long each takes and what fails.
Count suppressions by kind.
Check twenty sample tests and three recent features against pillars 1 and 3.
Look for repeated comments in recent human reviews. Each may indicate a missing rule, test, or documented decision, or an incorrect review. Verify the cause.
Score every pillar.
Engineering guidance
Check the instruction files, skills, and review gates.
Measure what each host loads every session. File sizes alone do not show this. In Claude Code, /context shows what loaded, as the Claude Code best practices describe.
Classify each instruction as durable or decaying, and as advisory or enforced.
List every “always” or “never” rule that is only advisory. Each one is in the wrong place, or it is a preference worded too strongly.
Find lines that restate the layout, scripts, or config. Keep the verification commands.
Find instructions that repeat the same meaning across files.
Check that review gates sort their findings and push back on over-fixing.
Ask for evaluation evidence. Without results, a written policy scores 1 and no policy scores 0.
What the report contains
The report has four parts, in this order:
An Evidence section.
One table row per pillar, with its score, evidence, top gap, fix, and channel. The channel column describes the proposed fix, not the current state.
The places where the skill was hard to apply.
Unverified checks and what you need to run them.
Order fixes first by blast radius, meaning how much damage a miss can do. Start with unenforced pillar 7 rules about secrets, protected paths, or irreversible actions. Also prioritize defects that hide those rules, such as instructions cut off by a size limit. Then order by durability, then by cost.
Figure 5. After blast radius, use the durability ranking introduced earlier.
Worked example: auditing this repository
Filip Stack is a repository and a body of guidance, so its audit ran both modes: existing repository for pillars 1, 2, 3, and 6, and engineering guidance for pillars 4, 5, 7, and 8.
The audit ran on 2026-11-01 at commit bc1587d1, in the same agent thread that wrote the skill, so it is not independent. No CI results were readable from the sandbox, so every score rests on a local run or on source inspection.
A fresh pnpm install --frozen-lockfile failed inside Claude Code's sandbox. One dependency ships a .env file in its package, and that machine's sandbox denies writes to **/.env*. On a workstation the same install works. Had the audit timed setup on a workstation, it would have scored pillar 6 against an environment the agent never gets.
Every pillar scored 1. Each had something written down or partly working, and each missed at least one level 2 criterion.
Audit scores for Filip Stack, in fix order
Pillar, in fix order
Top gap and fix
Bounded autonomyPillar 71/3
The rule against AI attribution in commits was advisory only, and a reminder the harness injects every session contradicted it.
Fix: A hook that blocks attribution trailers, plus ask rules for merges and 1Password. Enforced
Reproducible environmentPillar 61/3
A fresh agent worktree could not install dependencies inside the agent's sandbox.
Fix: Share installed dependencies into worktrees, or narrow the sandbox rule. Put the fresh-worktree command in AGENTS.md. Add a site preview per PR. Enforced and advisory
Test gatesPillar 31/3
No twenty-test sample, no single-test command in AGENTS.md, and the flake rate was unverified.
Fix: Run the sample. Add node --test <file> to AGENTS.md. Advisory
Static gatesPillar 21/3
About 4,700 lines of root scripts and tests had no static check.
Fix: Add a type check or Fallow to pnpm check. Enforced
Review gatesPillar 51/3
No configuration showed a read-only, fresh-context reviewer running on pull requests.
Fix: Decide whether a reviewer triggered by risk is worth its cost. Enforced
Code shapePillar 11/3
Boundary checks passed, but there was no duplication tool, so level 2 was not met.
Fix: Fallow, the same fix as pillar 2. Enforced
Guidance evaluatedPillar 81/3
The Workflow skills have baseline studies. The global guidance loaded on every task has none.
Fix: Run the decay test on the global guidance. Advisory
DocumentationPillar 41/3
Not every documented command was run, and the always-loaded global guidance was not decay-tested.
Fix: Prune it with the decay test. Advisory
Total
8 of 24
The audit also found five places where the skill was hard to apply. Each became a change to the skill:
A repository can need both modes.
Pillar 6 needed a meaning for guidance repositories.
Setup has to succeed inside the agent's sandbox.
The two-question test covers only repository facts.
Some checks need forge access.
Fixes merged since, in the report's order:
#83 added an optional guardrails plugin whose hook enforces the attribution and 1Password rules (pillar 7). On Codex, the 1Password prompt comes from a host-config rule, because Codex hooks cannot ask.
#79 put the fresh-worktree setup command and a single-test command in AGENTS.md (pillars 3 and 6).
#82 added Fallow to pnpm check for dead code, complexity, and duplication (pillars 1 and 2). Root scripts still have no type check, so pillar 2 remains partial.
An independent rerun on 2026-11-03 at 7c09fbed, using borrowed dependencies, scored 10 of 24. Code shape and test gates rose to 2. Fresh setup still failed inside the sandbox, so pillar 6 stayed at 1.
Where to start
For an existing repository, start with an audit. Install the companion skill, then ask your agent to audit the repository for agent readiness. Audit a repository explains what it checks and what the report contains.
Add the gates before you write code, while they cost the least. In this order:
Pillar 6: provide one command for setup, run, and teardown. Include a seed script and a health check. Verify it inside the agent's sandbox.
Pillars 2 and 3: add strict types, lint, dead-code and boundary tools, and a single-file test command. Run them through one check command that CI also runs and requires.
Pillar 7: deny rules and sandbox limits for every “never” rule.
Pillar 4: a short AGENTS.md with those commands. Add a line only after you have corrected the agent twice.
Pillars 1 and 5 grow with the code. Record each decision when you make it. Add review angles as risk appears.
Keeping guidance current
Guidance about agents, this lesson included, goes out of date in two ways.
Drift
A source changes, so a cited claim no longer matches what the vendor says.
Decay
A new model follows an instruction by default, so the instruction adds no value or does more harm than good.
Vendors retire advice as models improve. Pillar 8 applies to this guidance too. Test it with the models it targets. Add instructions only where you have observed a failure.
Review the guidance when any of these happens:
A frontier model that your agents use is released. Read its migration guide or release notes.
A source you cite, or a vendor changelog you watch, changes.
An audit result is disputed, or a score does not match how agents actually perform in that repository.
A quarter passes with no review.
The review steps are in the skill's maintenance procedure. For the decay test, set the tasks and budget first. Compare runs with guidance against runs without it. Then test the effect of removing one section at a time. Delete a section only when its removal makes no difference.
Each month, a scheduled agent can recheck sources, collect new guidance, and open a pull request with its findings. The remaining review steps need judgment and a person's approval. The decay test costs money because it runs paid evaluations.
Next steps
The agent-ready-environments skill gives agents the procedure taught in this lesson. Its install command is under Where to start.
OpenAI: Codex best practicesAllows a description of the repository layout in AGENTS.md. Anthropic's best practices list layout descriptions as outdated advice, and the skill follows Anthropic.
The score ladder, the fix order, and the durability ranking are the skill's own. The vendor guides do not rank the pillars.
The test layers in pillar 3 come from field practice. The vendors do not prescribe them.
An earlier draft of the worked example scored 12 of 24 under a looser rubric. The drop came from tightening the rubric, not from any change in the repository.