The Five Phases of AI Adoption in a Project

1Nothing added

This is where every project starts. The developer types every line of code themselves. Maybe there's autocomplete in the editor, but nothing in the project knows or cares that AI exists. The repository holds source code and nothing else.

There's nothing wrong with this phase. It's just the baseline.

2The developer prompts an AI

Now an AI agent sits between the developer and the code. The developer describes a change, the agent makes it, and the developer reviews the result.

The catch is that all the context lives in the developer's head and has to be typed again in every prompt. Each session starts from zero: "We use this framework, tests are run like this, don't touch that folder…" It works, but it doesn't scale, and the quality of the output depends on how well the developer remembers to explain things that day.

3AI context in the project

The natural fix for phase 2 is to write the context down in the project. The repository now holds a small set of documents written for the agent, not for humans: what the project is, how to build and test it, conventions, and the things that are easy to get wrong.

In my own projects that means files like these (one way to do it):

• CLAUDE.md / AGENTS.md: the project overview, the commands, and an index of where to find more.
• Context cards (cards/): small, lazy-loaded notes the agent reads only when the situation calls for them, so the main file stays short.
• project-plan.md: one shared file with the goal, non-goals, milestones, decisions and current state, which every agent session reads and updates.
• Standing defaults: decisions made once (e.g. "always use a Python venv") so they aren't debated again in every session.
• Project-scoped skills (.claude/skills/): repeatable workflows such as refactoring or reviews, checked into the repo so every agent and collaborator gets them.

The names are Claude Code's; other agents use AGENTS.md and similar files.

The application code itself hasn't changed yet. What changed is that the agent now starts every session already knowing the project. Prompts get shorter, and the results get more consistent.

Tests belong in this phase too, whether they're new or already there. Once the commands to run the unit and function tests are in the context docs, the agent checks that its change works before you look at it. Context tells the agent what to do; tests tell it whether it did.

This matters even more once you run more than one agent. If you orchestrate several agents in parallel, each in its own git worktree, none of them can borrow the context from your head. What's written in the repository comes along with every checkout, so each agent starts from the same conventions, commands and plan, and the decisions one agent records reach the others when its branch is merged. In phase 2, every extra agent means another long prompt; in phase 3, it's a short one.

4Architecture chosen for AI

From here on I'm looking ahead, so read this as suggestions rather than a report; the pieces exist today. In phase 3 the documentation adapted to the agent. In phase 4 I'd expect the developer to start choosing the architecture for it. Most of these choices are good for human developers too; the difference is that how an AI works becomes the tie-breaker whenever there's a design decision to make.

The trades I'd try first:

• Prefer small features with clear hooks over one big shared module. If each feature is a pipeline of named steps with hook points, an agent can add behaviour without understanding the whole system.
• Enforce rules with hooks rather than writing them in docs. Mechanical "always/never" rules can move out of the prose and into .claude/settings.json permissions and hooks. Then the harness enforces them, and the agent doesn't have to remember them.
• Give each feature an explicit contract instead of relying on conventions in people's heads. For example, a CLAUDE.md per feature with its steps and hooks, split into a short overview and a full contract once it grows.
• Measure code quality, not just correctness. The tests from phase 3 say whether a change works; measurements such as complexity, duplication, coverage and dependency rules say whether the structure is holding up. Keep the tests fast enough to run after every change, and turn the quality thresholds into checks the agent sees, so it corrects drift as it goes instead of leaving it for you.

My bet is that a well-structured project gives an agent less room to make mistakes.

5Safe enough for stakeholders to drive

This is the phase where the developer would stop adding features, and the one that takes the most nerve. It's the furthest out, so this is my guess at what it takes. It only works once the project is fully set up and safe, and you've seen that setup hold: the context is complete, the rules are enforced by hooks and permissions, and every change passes the tests and quality checks from the earlier phases on its way in. If a project is guarded that well, the people who want features could drive them directly. A stakeholder would work with their own AI session against the same project, inside the same guardrails, and features would come out the other end.

Review is the part I'd expect to have to scale. If the developer read every stakeholder change, they would simply become the bottleneck again, one pull request at a time. What I'd try is a second AI that reviews each change against the project's rules, alongside the tests and hooks, with a human stepping in only when the reviewer or a check flags something.

The developer doesn't disappear in this picture. They move to the other lane, from building features to looking after the system, with their AI pointed at the AI layer and the project's health:

• keeping the context documents and cards accurate as the code changes,
• tightening hooks, permissions and the reviewer's rules when an agent does something it shouldn't,
• refactoring where the quality measurements show the structure starting to drift,
• improving the tests and checks that let stakeholder-driven changes land safely,
• reviewing and auditing the agentic setup itself.

In short, the developer stops being the bottleneck for features and becomes the steward of the system that produces them.

Where is your project?

A quick way to place a project:

You don't have to rush, and different parts of a codebase can sit at different stages. If you're in phase 2, you're in good company: that's where most teams are. Writing your context down is a step almost any team can take today, and each step makes the next one possible. I'd expect stakeholder-driven work to hold up only on top of the context and guardrails that come before it.

None of this is free. Each step costs setup time and ongoing upkeep: context goes stale, hooks need tuning, and agents spend tokens reading it all. The last phase also widens who can trigger changes, so the guardrails would have to be treated like security controls, not conventions. That's a good reason to take the phases one at a time.