Your First 30 Days With AIDLC
You do not need an organization-wide program to start. One team, one repository and one month is enough to learn whether the cycle works for you. This page is a week-by-week plan for that team: capture a baseline, push one ticket end to end, put the first gates in CI, and close the month with a retro that decides what to keep. For the multi-team version, use the Rollout Playbook.
Why Start With One Team
Most failed adoptions fail the same way: a tool is handed to everyone, nobody agrees what "better" means, and a month later there is no evidence either way. A single team with a written baseline avoids that. It can change its own process without negotiating with anyone, and it ends the month with its own numbers instead of someone else's anecdotes.
Scope the month to one repository, one ticket tracker and a handful of people. Pick a codebase with decent tests and a team that is willing to write things down. Everything below is deliberately small: the aim is a working loop you can repeat, not a finished system. When the loop works, the Rollout Playbook explains how to spread it, and its small teams section covers the case where one team is the whole organization.
The Four Weeks at a Glance
Each week has one focus and one deliverable. Resist the urge to run them in parallel: the order matters, because each week produces the thing the next one depends on.
Baseline and setup
Measure how you work today, write the instruction file and usage policy, and agree the ticket contract fields. Deliverable: a baseline and the written ground rules.
One ticket, end to end
Take one small, real ticket through criteria, plan approval, tests first and review. Deliverable: one merged change with its evidence.
Gates in CI
Make the rules mechanical: no test edits, a mutation gate on one critical module, review depth by risk tier. Deliverable: a pipeline that enforces the policy.
Learn loop and retro
Turn what went wrong into the first rules, compare against the baseline, decide what to keep and what to measure next. Deliverable: a filled-in review.
Week 1: Baseline and Setup
Do not let an agent write a line of production code this week. The work is measurement and writing, and both are cheap now and impossible to reconstruct later.
Capture the baseline
From your tracker and Git history, pull the last two months for this team: lead time from ticket start to merge, review turnaround, change failure rate, reopened tickets and escaped defects. Rough numbers are fine; the point is a before to compare against. The Measuring Impact page explains which signals hold up.
Write the instruction file
One short file at the repository root that tells every agent how this codebase works: build and test commands, layout, conventions, and the things never to touch. Start under a page and grow it only from real mistakes. See Context Engineering.
Agree a usage policy
A half-page everyone signs off on: which tools are approved, which data classes may never be pasted into them, which actions need a human, and who owns exceptions. Align it with the Security and Compliance page and your own company policy.
Add the ticket contract fields
Extend your ticket template with the fields an agent needs: acceptance criteria with IDs, risk tier, data touched, feature flag and rollback. The Templates page has the full contract; start with those five fields only.
Invented example of a Week 1 baseline sheet:
TEAM: payments-api (5 engineers) PERIOD: last 8 weeks
Median lead time, ticket start to merge: [days]
Median review turnaround: [hours]
Change failure rate: [percent of releases needing a fix]
Reopened tickets: [count]
Escaped defects (found after release): [count]
Where the time goes (their own words): [one line from each engineer]Week 2: One Ticket, End to End
Choose one small, real, low-risk ticket: a bounded change with an obvious way to check it, in code the team understands well. Resist the dramatic first project. A boring ticket makes the process visible instead of the feature.
| Step | What happens | Evidence to keep |
|---|---|---|
| 1. Criteria | The owner writes Given/When/Then criteria with IDs, plus one "must never". Two engineers read them and list what an agent would have to guess. | The ticket contract, the guess list |
| 2. Plan | The agent proposes a plan: files to touch, approach, risks. A human approves or edits it before any code is written. | The approved plan |
| 3. Tests first | Failing tests are written from the criteria and run red. Only then does implementation start, with the tests locked. | The red run, one test per criterion ID |
| 4. Implement | The agent works until the tests are green, inside the boundaries in the plan. | The branch and the session notes |
| 5. Review | A human reviews against the criteria first and the diff second. Note what the review caught that the tests did not. | Review comments, any rework |
| 6. Merge | Merge behind the flag, confirm in production, and record the time spent at each step. | The timing sheet |
The full method behind steps 1 and 3 is on the ACDD page, and a worked case with invented numbers is on the Worked Example. If the ticket goes badly, that is useful: write down exactly where, because that is your first rule.
Week 3: Gates in CI
Week 2 relied on people remembering the rules. This week the pipeline remembers them. Add exactly three gates, then stop; more gates can wait for the learn loop to justify them.
No test edits
A check that fails the build when an agent-authored change modifies, deletes or skips a test that existed at plan approval. An agent that cannot edit the tests cannot make a failing test pass by changing it.
Mutation gate on one module
Pick the single module whose failure would hurt most and require a mutation score threshold on changes to it. One module keeps the run time small; the Testing Strategy page explains why passing tests alone are not enough.
Review by tier
Route the pull request by the ticket's risk tier: a low tier needs one reviewer, a high tier needs two and a named owner. See Code Review for what each tier looks at.
Illustrative gate policy (generic, adapt to your CI)
gates:
- name: tests-unchanged
rule: fail if any test file present at plan approval is
modified, deleted or marked skipped
- name: mutation
scope: src/billing/ # the one critical module
threshold: 70 # percent, tune from your baseline
- name: review-by-tier
low: 1 reviewer
medium: 1 reviewer + code owner
high: 2 reviewers + code ownerWeek 4: Learn Loop and Retro
Run two or three more tickets through the loop, then spend the end of the week turning the month into decisions. The Curate phase is where AIDLC compounds what it learns, and this is your first small turn of it.
Write the first rules
For each mistake of the month, ask what single line would have prevented it, and add that line to the instruction file or a gate. Keep only rules traced to a real incident; delete any that never fire.
Decide what to keep
Go through each practice and gate and vote: keep, change or drop. A practice nobody could explain the value of after a month is a candidate to drop, not to defend.
Pick what to measure next
Compare the new numbers with the Week 1 baseline, honestly, including where they got worse. Then choose one or two signals to add for month two from Measuring Impact.
Day-One Checklist
Everything that has to be true on the first morning, so Week 1 is spent measuring instead of hunting for access.
[ ] One repository, one tracker, one team named
[ ] A coding agent approved and installed for everyone on the team
[ ] A named owner for the 30 days (one person, not a committee)
[ ] The repository builds and its tests run from a clean checkout
[ ] Access to the last two months of ticket and Git history
[ ] A place to keep the baseline sheet and the retro notes
[ ] A calendar slot for the Week 4 retro, booked now
[ ] Everyone has read the usage policy draft
[ ] An agreed first ticket candidate for Week 2Daily Habits
Small, boring and repeated. These matter more than any single meeting.
Define before delegating
Never hand an agent a request you could not state as who, needs, why and must-never. See Problem Definition.
Read the plan, not just the diff
Approving a plan takes minutes; unwinding a wrong approach takes hours.
Log one friction a day
One line in a shared note: what slowed you down or surprised you. This is the raw material for Week 4.
Fix the instruction file at once
When an agent repeats a mistake, add the line that prevents it today, not at the retro.
Week-4 Review Template
One page, filled in together in the retro. Copy it into your wiki and keep each month's copy; a series of them is your adoption history.
30-day review
TEAM / PERIOD:
NUMBERS (baseline -> now)
Lead time:
Review turnaround:
Change failure rate:
Reopened tickets:
Escaped defects:
TICKETS RUN THROUGH THE LOOP: [count]
Went well:
Went badly, and exactly where:
FIRST RULES ADDED (each traced to an incident)
1.
2.
GATES: kept / changed / dropped
tests-unchanged:
mutation (module: ):
review-by-tier:
MEASURE NEXT MONTH (one or two signals):
DECISION: continue / adjust / stop, and why:
OWNER:Prompt: draft the review from your notes
Below are our baseline sheet, our daily friction notes and the
list of tickets we ran this month. Draft our 30-day review.
Rules:
- Use only the numbers I give you. If a number is missing, write
"not measured" instead of estimating it.
- For each friction note, propose ONE candidate rule and say which
incident it traces to.
- Flag any rule that would not have prevented a recorded incident.
- Do not recommend scaling to other teams.
Baseline: [paste]
Friction notes: [paste]
Tickets: [paste]Common Stumbles
The same few problems show up in most first months. Each has a cheap fix if you spot it early.
| Stumble | What it looks like | The fix |
|---|---|---|
| No baseline | At the retro everyone agrees it "felt faster" and nobody can prove it. | Capture rough numbers in Week 1, even if imperfect. |
| Starting with a hero ticket | The first ticket is large and risky, so the process gets blamed for the ticket's difficulty. | Choose a small, boring, well-understood change. |
| Vague criteria | The agent returns something plausible that misses the point. | Run the guess list before the plan; see Problem Definition. |
| Too many gates, too soon | CI takes so long that people route around it. | Three gates, one mutation module, and add more only from incidents. |
| An instruction file that only grows | Pages of rules nobody reads, some contradicting each other. | Every rule traces to an incident; prune any rule that never fires. |
| Skipping the retro | The month ends, the lessons stay in people's heads, and the second month repeats the first. | Book the retro on day one. |
What "Good" Looks Like at Day 30
Good is not a speed number. It is a team that can describe its process, show its evidence and decide what to do next. Seven outcomes:
A baseline exists and the new numbers sit beside it, including the ones that got worse.
An instruction file is in the repository and has been edited at least once because of a real mistake.
A usage policy is signed off by the team and visible to anyone who joins.
At least one ticket shipped with criteria, an approved plan, tests first and a human review.
The three gates run in CI and have blocked something, or been shown not to.
The first rules are written, each traced to an incident rather than a hunch.
The retro happened and ended in a decision: continue, adjust or stop. Where the answer is continue, the Maturity Model shows what the next level asks of you.
Frequently Asked Questions
Capture a baseline before changing anything: lead time, review turnaround, change failure rate, reopened tickets and escaped defects for the last two months. Then write a short instruction file, a half-page usage policy and the ticket contract fields. Week 1 should contain no agent-written production code.
A small, real, low-risk ticket in code the team understands well, with an obvious way to check the result. A boring ticket makes the process visible instead of the feature. A large or risky first ticket gets the process blamed for the ticket's difficulty.
You can show the Week 1 baseline beside the new numbers, at least one ticket shipped with criteria, an approved plan, tests first and human review, three gates running in CI, a first set of rules traced to real incidents, and a retro that ended in a decision to continue, adjust or stop.
Start With One Ticket
Book the retro, capture the baseline and pick a boring first ticket. The month takes care of the rest.