Onboarding a project for autonomous development with human gates
Software engineering has been evolving, and it is changing again in the age of agentic development. What hasn’t changed is code quality, and the quality gates that make sure the code is covered by tests and that the app is functioning correctly. I’m talking about unit tests and end-to-end tests as basic quality gates. In 2026, there is no excuse to not have at least unit tests for behaviour, and even better, end-to-end tests for feature function.
Below are my notes and the checklist I go through on every project I onboard, either a new project from scratch or an existing one. The process is the same, but existing projects require more attention: there is already a codebase, existing technical debt, and probably bad architecture to take into consideration for agents to work correctly.
Quick read: the article in one picture
flowchart TB
accDescr: Steps 1 to 4 are done once per repository; step 5, a spec approved by a human, is done at project level; then autonomous agentic development starts.
subgraph repo [Per repository]
audit([1. Audit: the gaps]):::human --> critical([2. Critical features, with business]):::gate
critical --> gates(3. Gates and structure):::check
gates --> context([4. Minimum AGENTS file]):::human
end
subgraph project [Project level]
spec([5. Spec approved by human]):::gate
end
context --> spec
spec --> dev[Autonomous agentic development]:::agent
classDef human fill:#e8f0ee,stroke:#006b56,color:#111827
classDef agent fill:#ffffff,stroke:#3d4654,color:#111827
classDef check fill:#f2f5f4,stroke:#6b7280,color:#111827
classDef gate fill:#e8f0ee,stroke:#006b56,stroke-width:2px,color:#111827
The checklist at a glance
| Step | What I do | What it produces |
|---|---|---|
| 1. Audit | List what exists and what is missing | A gap list |
| 2. Critical features | Agree with the business which features must never break | A scenario checklist |
| 3. Minimum gates and structure | Lint, unit tests, coverage, end-to-end tests, layers | Scripts agents can run |
| 4. Agent context | A minimum AGENTS file | Rules and pointers agents read |
| 5. Spec process | How specs are written and approved by a human | Clear instructions for development agents |
These steps are needed for a fully automated pipeline where AI agents are doing the development implementation, to keep the application stable.
- The research for this post found no study that tests these five steps as a sequence. The sequence is my experience; the sources below back the steps one by one.
Sources. Anthropic’s Claude Code documentation says that “in most cases, your first plain prompt in a fresh session already does the right thing, without any setup on your part”, and also: “If it has nothing to run that tells it whether the work actually is done, “looks done” is all it has to go on. In practice that makes you the test suite.” (Best practices for Claude Code)
1. Audit the project
Identify what the project already has as quality gates and automations :
- architecture, folder structure and layers (controllers, services, components…),
- security,
- code linters,
- unit tests and code coverage,
- end-to-end, integration and performance tests,
- CI/CD, and whether deployment is manual or automatic,
- agents in the project
- known technical debt
This first audit will give us the gaps to fill, and the rollout process for step 3 as minimum requirements.
Sources.
- Google: “74.45% of the code changes and 69.46% of the edits were generated by the LLM” (Migrating Code At Scale With LLMs At Google).
- Airbnb: a test migration estimated at “1.5 years of engineering time” finished in “6 weeks”; “when a check fails, we bring in the LLM to fix it” (Accelerating Large-Scale Test Migration with LLMs).
- Birgitta Böckeler: “the harness is most needed where it is hardest to build” (Harness engineering for coding agent users).
2. Review the critical features
The critical features are, or should be, defined with the product partner, or someone in the company who knows the critical features of the app pretty well. We need to test mainly the features that, if broken, would highly disturb the service for users. For example :
- authentication,
- the onboarding process,
- sales funnels,
- the checkout process.
These scenarios become the baseline for end-to-end tests of step 3. They could also identify the need for more complete test setup like performance tests.
3. Plan the minimum gates and the target structure
I plan the onboarding and the rollout step by step. The minimum setup to start a fully automated development pipeline:
| Gate | Why |
|---|---|
| Linter (and type check, where the language has one) | Style and structure rules the agent cannot argue with |
| Unit tests | Behaviour |
| Test coverage, with a floor the build enforces | New code arrives with its tests |
| End-to-end tests on the critical features, with dockerized environments | The app still works for users |
| CI/CD for quality gates by PRs, environment deployment (sandbox, production) | Automate the process |
Each gate comes with a clear script, for agents to easily run and investigate. Passing the gates is not enough on its own:
- agents can make tests pass without fixing the code,
- passing PRs still fail human review,
- so a review step is always necessary before validating a PR
The code review step is also a key part of the agentinc development onboarding, since every feedback on the PRs can be used for self learning to improve the agents setup.
Sources.
- Simon Willison: “If your project has a robust, comprehensive and stable test suite agentic coding tools can fly with it” (Vibe engineering).
- METR: “roughly half of test-passing SWE-bench Verified PRs written by mid-2024 to mid/late-2025 agents would not be merged into main” (Many SWE-bench-Passing PRs Would Not Be Merged into Main).
- An agent “with access to unit tests may delete failing tests rather than fix the underlying bug” (ImpossibleBench).
The structure: where agents write code
From experience on a React Native app that was missing structure and architecture layers: agents would sometimes write database access imports in the controller layer, instead of the service.
For this project I decided to start a migration process for new features, because a backend migration was also part of the scope :
- a new folder structure following clean/hexagonal architecture layers,
- every new feature goes in the new architecture,
- legacy features are migrated progressively, behind a human gate,
- the code reviewer agent is prompted to verify the architecture structure for new code. That is where the database imports were caught and fixed.
An organized project allows agents to know where to write code for each layer.
Sources.
- Models show “strong accuracy for explicit, code-inferable decisions”, in a study of architecture decision records across 109 repositories (Evaluating Large Language Models for Detecting Architectural Decision Violations).
- Anthropic: “If something has to happen every time, make it a hook, a deny rule, or a managed setting” (Best practices for Claude Code).
- Böckeler: “Computational sensors catch the structural stuff reliably” (Harness engineering).
4. Set up the project context for agents
A minimum AGENTS file, and minimum is the point: a long file costs tokens and does not make agents better.
What goes in it, only what the code does not already show:
| Section | What it holds |
|---|---|
| Quality gates | The command that runs them all, and what CI checks that the scripts don’t |
| Guardrails and security blockers | Each rule with where it is enforced (lint rule, hook, CI); anything that must hold every time lives there, not in the file |
| Project structure | A pointer to the rule that enforces the layers, not an overview |
| Domain and business wording | Where business terms differ from the names in the code |
| Scripts from step 3 | Only those an agent would not find in package.json: prerequisites, ports, fixtures |
| Known pitfalls | Mistakes agents have already made |
Sources. A controlled study from ETH Zurich found that “providing context files does not generally improve task success rates” while “increasing inference cost by over 20% on average”, that “context files are not effective at providing a repository overview”, and that a file “should only contain specific additional instructions beyond what is already available in the codebase” (Evaluating AGENTS.md).
5. Define the spec definition process
The specs and the design need to be done with a human beforehand. If the specs are clear, the development agents need simple and clear instructions.
- A clear spec does not make an agent follow it, so the gates from step 3 are still needed.
- I personally started with GitHub Spec Kit for small features in 2025, then evolved to the BMAD Method for bigger scope features.
- BMAD is more complete, and is inspired by the Agile method (“Agile AI-Driven Development”).
Sources.
- Böckeler, trying three spec tools, “frequently saw the agent ultimately not follow all the instructions” (Understanding Spec-Driven-Development).
- Spec Kit’s README now presents it as a toolkit for “SDD or any other process” (github/spec-kit).
Steps 1 to 4 are done per repository. After multiple iterations, I have managed to have stable apps after a big development iteration, with good results on new PRs. At this point I stopped managing my repositories individually, since sometimes decisions comme from a larger project context. So now step 5 is on a project level, instead of repository level. I will share more about the details on a following article.