AI-DLC With Claude Code: A Working Setup

Installing AI-DLC in Claude Code takes four commands. Running it well takes a repository the agent can read and the discipline to stop at the gates.

AI-DLC 2 runs inside seven coding agents, and Claude Code is the one its own documentation uses for every example. The README recommends Claude Opus 4.8 as the model. It is also one of the two agents I run every day, next to pi, so this is the setup I would hand to a team that wants to try the method on Monday. I ran every step below on a clean test project with release 2.10.0 before writing it down.

If you have not read what the method is, start with what AI-DLC is. If you know version 1 and want to know what moved, read what AI-DLC 2 changed. This article is the hands-on part: the commands from the official docs, in order, plus the habits the docs leave to you.

Before you install: give the agent something to read

One of the first things AI-DLC does in an existing project is reverse-engineer it. A developer agent scans the code and an architect agent writes up what it found, and every requirement, story, and Unit after that builds on the write-up. If the repository is hard to read, the write-up is a guess, and so is everything downstream.

So the first step has nothing to do with AI-DLC. Put a short AGENTS.md or CLAUDE.md at the root of the repo with four things: the stack and versions, the patterns the team uses, the libraries you forbid and why, and one example of each pattern (a typical endpoint, a typical domain function, a typical test). I wrote a whole guide on AGENTS.md as the agent’s memory. Every gap you fill here is a question the agent will not have to ask you in the middle of a mob session.

AI-DLC writes its own onboarding into .claude/CLAUDE.md when you configure the project. That file teaches Claude Code the method. Your root file teaches it your system. Keep them separate.

The second thing also has nothing to do with the tool. Your team should already be writing specs before letting an agent build. If it is not, AI-DLC will hand you a stream of requirements documents to approve that nobody on the team knows how to judge. Start with how to write a spec and come back when that feels normal. The reasoning is in AI-DLC vs Spec-Driven Development.

Step 1: install the engine

The installer adds a native aidlc command and the runtime for every supported agent. It does not need Bun or Node.js.

Install AI-DLC

1. macOS, Linux, or WSL

   $ curl -fsSL https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.sh | sh

2. Windows PowerShell

   PS> irm https://github.com/awslabs/aidlc-workflows/releases/latest/download/install.ps1 | iex

If your shell cannot find aidlc afterwards, follow the PATH instruction the installer prints, or open a new terminal on Windows. Run it from a normal PowerShell window, not one opened as administrator.

On Linux there is one catch the installer message does not spell out. The hooks that drive AI-DLC are started by Claude Code, not by your interactive shell, so they do not read your .bashrc. If aidlc is only on the PATH of your terminal, aidlc doctor warns that it is “interactive-only”. Put ~/.local/bin on the PATH your session inherits (a file in ~/.config/environment.d/ works), or let aidlc config runtime sort it out.

Step 2: configure the project

Configure the project

1. Go to the project root

   $ cd /path/to/your-project

2. Install the Claude Code integration

   $ aidlc config --harness claude

3. Check the setup

   $ aidlc doctor

aidlc config is local and transactional. It writes the Claude Code integration, creates an aidlc/ workspace, merges what it needs into your project files, and records a baseline so later refreshes know what it owns. If you want to see the plan before anything is written:

aidlc config --dry-run

Two options are worth knowing on the first run. AI-DLC can install five MCP servers for Claude Code: Context7 for library docs and four AWS servers (API access, pricing, infrastructure as code, serverless). Missing credentials make a server unavailable without blocking a workflow, but if you do not build on AWS there is no reason to load them.

aidlc config --harness claude --mcp none

And AI-DLC does not pick your model provider. It keeps whatever Claude Code already uses. If you want Amazon Bedrock, aidlc config providers walks you through it; otherwise leave it alone.

What aidlc config wrote into a clean project

• your-project/
  • AGENTS.mdyours// stack, patterns, forbidden libraries
  • .claude/
    • CLAUDE.mdaidlc// the method's onboarding
    • settings.json// hooks, status line, welcome banner
    • agents/// the 14 agent personas
    • skills/aidlc/// the /aidlc command
    • hooks/// audit, guards, recovery, status line
    • tools/// the deterministic engine
  • aidlc/spaces/default/memory/commit// org, team, project, and phase rules
  • .gitignore// an AI-DLC block that says what to commit

The record folders for each piece of work (aidlc/spaces/default/intents/) appear on your first /aidlc, and a knowledge/ folder for team documents appears when you add some. Commit the aidlc/ folder as it fills up. Doctor reminds you if you do not, because those records travel between teammates by git: the rules, the state of each workflow, the artifacts, and the audit trail. The block AI-DLC adds to .gitignore lists exactly what is meant to be committed and what is machine-local.

Step 3: approve the hooks and restart

This is the step people skip, and then nothing works. AI-DLC on Claude Code runs on hooks: scripts Claude Code fires on events, which log the audit trail, validate state before compaction, enforce the approval guards, and drive the status line. The engine wires 17 of them.

Claude Code does not run project hooks you have not approved. Open Claude Code in the project, run /hooks, approve them, and restart Claude Code completely. Then run aidlc doctor again.

If doctor still complains about hooks, two causes cover most cases. Either hooks are disabled somewhere in your Claude Code settings layers, or your company’s managed settings allow only managed hooks, in which case only the person who administers Claude Code can lift it. Doctor names which one it is.

Step 4: start a workflow

Open Claude Code in the project and describe the work:

/aidlc Build a REST API for inventory management

AI-DLC reads the request and proposes a workflow profile with its stage count and depth. You confirm it or change it. You can also name the profile yourself:

/aidlc classic
/aidlc feature Add customer notifications
/aidlc bugfix Fix the login timeout

If you already have a vision document or a PRD in the repo, point at it by exact path and the workflow reads it as input:

/aidlc Read ./docs/vision.md and build what it describes

From there the agents take turns. Each interactive stage asks how you want to answer: Guide Me (the agent asks structured questions), Edit File (you fill in the questions file yourself), or Chat (free conversation, and the agent extracts the decisions). Every stage ends at a gate where you answer Approve or Request Changes in your own words. “Looks good but split the tests” counts as a change request, and those words become the feedback.

Claude Code also gets a status line at the bottom of the terminal: the current phase, the stage, a progress bar, the lead agent, how much context remains, and an estimated token cost. The cost is a list-price estimate, not your bill, but watch it on the first runs. An AI-DLC workflow reads and writes a lot.

Context discipline: the part the docs leave to you

A one-million-token window sounds like infinite room. It is not. In the rollout I followed, an Inception on a real repository used half of it or more by itself: the reverse engineering, the questions, the requirements, the design. And the quality of the answers dropped noticeably once the window passed about three quarters full. The agent did not crash. It got sloppy, and sloppy at a gate is how wrong decisions get approved.

Research says the same thing from another angle. When a long session compacts its history to make room, constraints quietly disappear. One study measured agents obeying a rule 100% of the time while the rule was visible, then violating it in 30% of episodes after compaction, up to 59% for some models (Governance Decay). Another found compactors keep only 17% of the constraints a user set during the session (Lost in Compaction).

AI-DLC 2 protects its own state against this. The workflow lives on disk in the state file and the record folder, and a hook writes a recovery checkpoint before Claude Code compacts. What it cannot protect is the nuance you discussed and never wrote down. So these are the habits that held up:

Session habits for AI-DLC in Claude Code

1. 01

   Check the window before Inception starts.

   Inception is the heaviest phase. Use a model with the largest context window your plan offers, and confirm how much room you actually have before the reverse engineering eats it.

   Type this

   /context

2. 02

   Clear only at a gate, after committing.

   Clearing in the middle of a stage throws away work that is not on disk yet. At a gate, everything that matters is in the record folder. Commit and push the record, then clear, then resume from the state file.

   Type this

   /clear
   /aidlc --resume

3. 03

   Park instead of pushing through a tired session.

   After an hour of reading generated documents, people approve without reading. Parking stops at the current stage boundary and costs nothing.

   Type this

   /aidlc park

4. 04

   Ask where you are without moving anything.

   Status is read-only: phase, stage, progress, which settings are on and where each came from.

   Type this

   /aidlc --status

5. 05

   Before clearing a stuck session, make it write down what it learned.

   When a session is going in circles, clearing it also throws away the dead ends it already ruled out. Have it write them down first, then start fresh from the file.

   Type this

   Write a summary of this problem to notes/handoff.md: what we found, the hypotheses we verified, the ones we discarded, and the next step. Do not change anything else.

When you close Claude Code and come back tomorrow, run bare /aidlc. It reads the state, checks the recovery checkpoint, and offers four choices: resume from the last checkpoint, redo the current stage, jump to a stage, or start a new piece of work alongside. If the checkpoint and the state disagree because a compaction hit mid-stage, it warns you, and the safe answer is to redo that stage.

Model settings worth touching

AI-DLC splits its 14 agents into three groups for model policy: Deciding (nine agents, from product and architecture to development, security, quality, and the composer), Reviewing (the two reviewers), and Writing up (delivery, pipeline and deploy, operations). You can set the effort per group, or per agent, and commit the policy for the whole team.

aidlc config models --show
aidlc config models --reviewing-effort xhigh --project --yes

The first command shows what every agent will run with and where that came from. The second is the one change I would make first: the reviewers are the agents that catch what the builder missed, so give them more thinking, not less. The first-run wizard defaults to a balanced preset at medium effort for every group. A thorough preset raises the reviewers to xhigh; a minimal one lowers the writing-up agents.

One more setting belongs in the repo, not on each laptop. Pin the engine version so everyone on the team runs the same workflow definitions:

aidlc config --pin 2.10.0

That writes .aidlc-version to the project. Commit it.

Keeping it updated

aidlc update updates the engine on your machine. It does not touch your projects. Refresh each project between workflows:

aidlc update
cd /path/to/your-project
aidlc doctor
aidlc config

aidlc config refuses to refresh a project while a workflow is active, so finish or park the current piece of work first. If you use plugins, run /aidlc plugin sync inside Claude Code after the refresh.

When something does not work

From the repository's troubleshooting table. Run aidlc doctor first; it names the fix.

Symptom	What fixes it
The shell cannot find aidlc	Apply the PATH instruction the installer printed, or open a new terminal on Windows.
Doctor says aidlc is interactive-only	The hooks do not see your shell's PATH. Add ~/.local/bin to the session PATH or run aidlc config runtime.
Doctor warns about uncommitted changes under aidlc/	Commit and push the aidlc/ folder. It is how the team shares rules, state, and the audit trail.
Doctor reports a project and runtime version skew	Finish the active workflow, then run aidlc config.
Gates and status line never appear	Approve the project hooks with /hooks and fully restart Claude Code.
Plugin stages disappeared after a refresh	Run /aidlc plugin sync.
Refreshed skills do not take effect	Start a new Claude Code session.

Where pi fits

I use pi every day, and it is not one of the seven harnesses AI-DLC 2 supports. I am not going to pretend otherwise or invent a workaround.

What pi does have is pi-sdd-kit, my Spec-Driven Development skill pack, and that is the honest place for it in this story. Most teams are not ready for AI-DLC on day one, because they do not specify yet. A lighter workflow (write the requirements, approve them, design, cut tasks, build, review) is how a developer builds that habit alone, before a team builds a lifecycle on top of it. Specify in pi until it is boring. Then run AI-DLC in Claude Code for the work that needs more than one person to decide. If you live in Claude Code already, the same habit is in Spec-Driven Development with Claude Code.

Your first week

A setup that teaches you something

• ✓Required:
  Root AGENTS.md written: stack, patterns, forbidden libraries, one example each.
• ✓Required:
  Engine installed, project configured, hooks approved, doctor clean.
• ✓Required:
  Engine version pinned with aidlc config --pin and committed.
• •Optional:
  Reviewer effort raised; MCP servers you do not need left out.
• ✓Required:
  One real feature run end to end on the Classic profile.
• ✓Required:
  Sessions kept to about an hour, cleared only at gates, record committed before every clear.
• ✗Anti-pattern:
  The whole 33-stage Feature profile on day one.
• ✗Anti-pattern:
  A one-line fix run through AI-DLC to try it out.

FAQ

Does AI-DLC work with Claude Code?+

Yes. Claude Code is one of the seven harnesses AI-DLC 2 supports, alongside Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode, and GitHub Copilot. Configure the project with aidlc config --harness claude and start workflows with /aidlc.

Do I need Amazon Bedrock to use AI-DLC with Claude Code?+

No. AI-DLC keeps the model provider Claude Code already uses. Bedrock is an explicit option you can choose with aidlc config providers.

Which model should I use?+

The README recommends Claude Opus 4.8. For long Inception phases on large repositories, the size of the context window matters as much as the model, so use the largest window your plan offers and watch it with /context.

How do I resume an AI-DLC workflow after closing Claude Code?+

Run /aidlc in the project. It reads the state file and offers to resume from the last checkpoint, redo the current stage, jump to a stage, or start a new piece of work. /aidlc --resume skips the menu and continues directly.

Can I use AI-DLC with pi?+

Not as a supported harness. AI-DLC 2 ships for seven agents and pi is not one of them. pi-sdd-kit gives pi a lighter Spec-Driven Development workflow, which is the habit AI-DLC assumes your team already has.

How do I update AI-DLC?+

Run aidlc update to update the engine on your machine, then refresh each project between workflows with aidlc doctor and aidlc config. Pin a version per project with aidlc config --pin so the whole team stays on the same one.

Where to go next

The installation is the easy part, and it really is four commands. The hard part is everything around it: a repository the agent can read, a team that knows how to judge a spec, and the patience to stop at the gate instead of rushing through it.