JOURNAL
Part 1/6: Architecture of an agentic workflow and choosing models by role
A 7-step loop with two human gates, risk tiers that decide how much autonomy an agent gets, models chosen by role (Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, Codex gpt-6.1-sol), and a 20-task eval on your own work, all on the agentic-shortlink sample repo.

On this page
Want the deep dive? The full 25-minute video takes one feature through the whole loop, and the playlist also has a vertical cut for phones.
Most people start with AI coding agents the same way: open Claude Code or Codex, describe a feature, watch it write code, and merge if it looks right. On a toy script that works. On a real project with a team, users and a CI pipeline, it stops working within a few weeks. Not because the agent writes bad code every time, but because nobody can say with confidence which of the changes it produced are correct.
This series is about fixing that. Over six parts we build a repeatable, controlled workflow for shipping software with agents, on a small sample repo you can clone and run. Part 1 is the map: the loop every change goes through, who does what at each step, how risk decides how much freedom the agent gets, and which model to put in which role. The later parts turn each box on that map into files, scripts and CI jobs.
What you will have at the end
- A 7-step loop (Spec, Plan, Execute, Verify, Review, Merge, Learn) with two human gates, and for each step the person or agent that runs it, the artifact it produces and the check that ends it.
- A rule for how much autonomy an agent gets, tied to the risk of the change and written down in
AGENTS.md. - A model-by-role plan with concrete model ids for November 2026, and a 20-task procedure to test it against your own work instead of a leaderboard.
- A clear picture of how Claude Code and Codex are configured side by side in the same repo.
- The sample repo
agentic-shortlinkcloned on your machine withpnpm checkpassing.
Prerequisites
- Git and Node 22 or newer (the repo pins
22in.nvmrc).corepackships with Node and gives you the pinned pnpm. - Claude Code or Codex installed is useful but not required for this part. Installation and repo setup are covered in Part 2.
- This is the first part of the series. The principles behind it are in the prequel post on agent speed and control. Reading it first helps but is not required.
Why “just prompt the agent” breaks on real projects
An agent can produce a working pull request in minutes. A careful human review of that pull request still takes as long as it did before agents existed, sometimes longer, because you did not write the code and have no memory of why it looks the way it does. When you run two or three agents in parallel, output grows faster than your capacity to review it. That is the first thing that breaks.
The second thing that breaks is intent. A one-line prompt like “add link expiry” leaves dozens of decisions open: what status code an expired link returns, whether expired clicks still count, what happens to links created before the change. The agent will pick an answer for each one. Some picks will be reasonable, some will not, and you only find out which when a user does.
In my own work the pattern has been consistent: once agents write most of the code, the slow and valuable parts of the job move to the two ends of the process. At the start, specifying exactly what “done” means. At the end, verifying that it really is done, with evidence instead of a feeling. The prequel post makes this argument in more detail. This series is the hands-on version: every principle becomes a file in a repo.
So the architecture we want is not “one smart agent”. It is a loop where:
- a human decides what to build and approves how,
- agents do the bulk of the typing, inside boundaries they cannot step out of,
- machines check what machines can check (lint, types, tests),
- a second and third opinion check what tests cannot,
- and a human signs off on evidence, not on vibes.
The loop: seven steps, two human gates

Every change in the sample repo goes through the same loop. Small changes go through it quickly and some steps shrink to a single command, but no step is skipped silently. Here is what each step means in practice.
1. Spec
Who: a human writes it, an agent sharpens it. Input: a feature idea. Output: a file in docs/specs/NNNN-name.md built from docs/specs/TEMPLATE.md: problem, scope in and out, a Behaviour table of concrete request/response rows, a Definition of done, and a Risk section. Ends when: the spec status is approved and every Definition of done line can be checked by a machine or by reading one file.
The repo has a new-spec skill that does the sharpening: it reads the template and recent specs, reads the code the feature will touch, asks up to five questions, writes the spec, and stops without writing code. Part 3 walks through it.
2. Plan, then the first human gate
Who: a strong model in read-only mode (plan mode in Claude Code). Input: the approved spec, AGENTS.md and the files the spec mentions. Output: docs/tasks/NNNN-name.md, a table of tasks with columns # | Task | Files | Check | Depends on, plus a note on which tasks can run in parallel. Ends when: a human reads the table and approves it.
This gate is cheap and very effective. Reading a five-row task table takes a couple of minutes. Reading the 400-line diff that a wrong plan would produce takes much longer, and by then the agent has already spent the tokens. The repo contains a real example from spec 0001:
docs/tasks/0001-link-expiry.md
| # | Task | Files | Check | Depends on |
| --- | --- | --- | --- | --- |
| T1 | Add nullable `expires_at` column and map it in `LinkRepo` | `src/db.ts`, `src/repo.ts` | `pnpm typecheck` | none |
| T2 | Accept `expiresInDays` in `POST /api/links`, compute `expiresAt` from the injected clock | `src/app.ts` | `pnpm vitest run test/expiry.test.ts -t "sets expiresAt"` | T1 |
| T3 | Add `isExpired`; return 410 on redirect and `expired` in stats; do not count clicks | `src/app.ts` | `pnpm vitest run test/expiry.test.ts` | T2 |
| T4 | Update README API section | `README.md` | review | T3 |
| T5 | Full gate | none | `pnpm check` | T1-T4 |
Parallelism: T1-T3 touch the same files, so they run in sequence in one worktree. T4 can run in parallel once T3's response shape is fixed.
Notice that every task has its own Check command. That column is what lets an agent know when it is finished without asking you.
3. Execute
Who: an executor agent, usually a mid-tier model. Input: one task (or a few tasks that share files). Output: commits on a branch in its own git worktree. Ends when: the task’s Check command is green.
The worktree matters. Each task gets a separate checkout on its own branch, so two agents never edit the same working copy, and you can throw a failed attempt away with one command. The repo script scripts/agent-task.sh creates .worktrees/<name> on branch agent/<name>, runs Claude Code or Codex headless inside it, and writes a summary to agent-runs/<name>/. Nothing is pushed. Part 4 covers it in detail.
4. Verify
Who: machines first, the agent second. Input: the branch. Output: a passing pnpm check (lint, typecheck, tests) and, for route changes, a test that exercises a Behaviour row through the app. Ends when: the full gate is green. If it fails, the loop goes back to Execute.
Verification is deliberately boring. The agent must run the same command a human would run, and report which command proved what. AGENTS.md asks every agent to finish with a summary in three parts: done and verified (with the command), done but not verified, skipped. That format makes it obvious when “done” really means “I think so”.
5. Review, then the second human gate
Who: one or two AI reviewers, then a refuter. Input: the diff against main and the spec. Output: a short list of findings, each with a concrete failure scenario (input leads to wrong output). Ends when: every confirmed finding is fixed or explicitly accepted, and a human has looked at the diff together with the evidence.
The refute pass is the part people skip, and it is the part that keeps review useful. AI reviewers produce false positives. If you pass all of them back to the executor, it will “fix” code that was correct. The repo’s refuter subagent receives the findings and tries to prove each one wrong, by reading the code and, when useful, writing a throwaway test. Only findings that survive go back to Execute.
The human gate here is not “read every line again”. It is: read the spec’s Behaviour table, read the evidence (which commands passed, which findings survived), and spend your attention on the parts the evidence does not cover.
6. Merge and deploy
Who: a human clicks merge; CI does the rest. Input: an approved pull request. Output: a commit on main and whatever your deploy pipeline does with it. Ends when: CI on main is green. In the sample repo, .github/workflows/ci.yml runs install, lint, typecheck, test and build on every pull request and every push to main.
7. Learn
Who: the human, often with an agent drafting. Input: what went wrong or was slow in this round. Output: a small change to AGENTS.md, a skill, a hook or the spec template. Ends when: the lesson is in a file that the next agent run will read.
This is the step that makes the whole system get better over time. If a reviewer keeps finding Date.now() in route handlers, you do not keep fixing it by hand; you add a line to the Code rules in AGENTS.md and a high-severity rule to the Code Review Rules. Part 6 is about running this step on purpose.
The loop on one page
| Step | Who | Artifact | Gate |
|---|---|---|---|
| 1 Spec | Human writes, agent sharpens (new-spec) | docs/specs/NNNN-name.md | Status approved; every Definition of done line is checkable |
| 2 Plan | Strong model, read-only (plan mode) | docs/tasks/NNNN-name.md | Human approves the task table |
| 3 Execute | Executor agent in a worktree | Commits on agent/<name> | Task’s Check command passes |
| 4 Verify | CI commands, run by the agent | pnpm check output, summary | Full gate green, else back to Execute |
| 5 Review | AI reviewer(s) + refuter | Confirmed findings list | Human approves diff + evidence |
| 6 Merge | Human merges, CI runs | Commit on main | CI green on main |
| 7 Learn | Human, agent drafts | Edit to AGENTS.md, skill or hook | Lesson is in a file the next run reads |
Check: after cloning the repo (see the tour below), confirm the spec and task artifacts exist.
$ ls docs/specs docs/tasks
docs/specs:
0001-link-expiry.md
0002-daily-click-stats.md
TEMPLATE.md
docs/tasks:
0001-link-expiry.md
Spec 0001 has gone through the whole loop. Spec 0002 is approved but has no task file yet: that is the exercise for Parts 3 to 5.
Risk tiers decide how much autonomy the agent gets
Running the full loop with two reviewers for a typo fix is a waste. Letting an agent merge a schema change on green CI alone is reckless. The answer is to sort changes by risk and let the risk tier decide which gates apply. I use three tiers:
- Low: easy to reverse, no effect on users or data. Tests, docs, pure helpers. Machines can decide.
- Medium: changes behaviour users can see, but reverting the commit undoes it. Routes, queries, validation. Machines plus one AI review plus one human.
- High: hard to reverse or affects trust. Database schema, authentication, CI workflows, dependencies. Everything above, plus a second AI reviewer from a different model family.
The important part is that this is written down where every agent reads it, not kept in someone’s head. In the sample repo it is the last section of AGENTS.md:
AGENTS.md
## Review levels
| Change | Required before merge |
| --- | --- |
| Tests, docs, `src/lib/` helpers | CI green |
| Routes, repo, validation | CI green + AI review + one human approval |
| Schema, auth, workflows, dependencies | CI green + AI review from two model families + human approval |
The three rows map directly to the three tiers. The table is also wired into the rest of the process. The spec template has a Risk section that asks “Reversible? Data migration? Public contract change? Pick the review level from AGENTS.md.” The new-spec skill tells the agent to state which review level applies. And the Safety section of AGENTS.md keeps agents away from the high-risk files unless the task is about them: “Never edit .github/workflows/ or AGENTS.md itself unless the task is about them.” In .claude/settings.json the same files sit on the ask list (Edit(.github/**), Edit(AGENTS.md)), so Claude Code has to ask before touching them even when the instruction is forgotten.
Risk also decides how long the agent may run alone. For a low-risk task I let the executor run headless to the end. For medium risk the plan gate is mandatory. For high risk I keep the agent in plan mode until the human has read the plan, and the change gets the cross-family review described in the next section.
Check: the review levels are in the file your agents read.
$ grep -A6 "## Review levels" AGENTS.md
## Review levels
| Change | Required before merge |
| --- | --- |
| Tests, docs, `src/lib/` helpers | CI green |
| Routes, repo, validation | CI green + AI review + one human approval |
| Schema, auth, workflows, dependencies | CI green + AI review from two model families + human approval |
Models by role
Once the loop is clear, choosing models gets easier, because you are no longer asking “which model is best?”. You are asking “which model is best for this role?”. The roles have different needs. A planner needs judgement and a long view of the codebase; it runs rarely, so a slow, expensive model is fine. An executor runs many times a day and needs to be reliable and cheap enough. A reviewer needs to be good at finding problems and, ideally, different from the model that wrote the code.

Here are the roles with the concrete model ids I use in November 2026, and where each one appears in the sample repo.
| Role | Needs | Models (Nov 2026) | Where in the repo |
|---|---|---|---|
| Planner / orchestrator | Judgement, reads a lot, runs rarely | Claude Opus 5.5 (claude-opus-5-5), Claude Fable 5.2 (claude-fable-5-2) for the hardest work, or gpt-6.1-sol with high reasoning effort | Plan mode in Claude Code; examples/codex/deep-review.config.toml (effort high) |
| Executor | Reliable edits, many runs, cost matters | Claude Sonnet 5.5 (claude-sonnet-5-5) or the Codex default model | scripts/agent-task.sh (--model sonnet); .codex/config.toml (gpt-6.1-sol, effort medium) |
| Primary reviewer | Finds real bugs, follows review rules | Claude Opus 5.5 | .claude/agents/reviewer.md (model: opus); ai-review-claude.yml (--model claude-opus-5-5) |
| Second-opinion reviewer | A different model family | gpt-6.1-sol through Codex | ai-review-codex.yml; scripts/cross-review.sh |
| Router / triage / extraction | Fast and cheap, short inputs | Claude Haiku 5.5 (claude-haiku-5-5) or a small GPT model | gateway/litellm.config.yaml |
| Sensitive or offline work | Data never leaves the machine | A local open-weight model via Ollama | local-coder in gateway/litellm.config.yaml; codex --oss |
A few notes on the table:
claude-opus-5-5is Claude Code’s default model. The aliasesopus,sonnet,haikuandfablework in--modeland in subagent frontmatter, which is why the repo’s agents and scripts use the short names.- The Codex docs list
gpt-6.1-sol,gpt-6.1-terra,gpt-6-astraandgpt-6-luna;gpt-6.1-solis the one used in the docs examples and in this repo. Codex sets reasoning effort separately withmodel_reasoning_effort, so the same model can play the executor role atmediumand the planner role athigh. - The
refutersubagent runs onsonnet. Trying to disprove a specific finding is a narrower job than finding problems in a whole diff, so a mid-tier model is enough. - For local models, Codex documents
codex --osswith Ollama and recommends a context window of 64k or more. The gateway config in the repo routes the namelocal-codertoollama_chat/qwen3-coder; Part 4 sets that gateway up.
Why the second reviewer should come from another family
When one model plans, writes and reviews its own work, its blind spots line up. If it misread the spec while planning, it will misread it the same way while reviewing, and it will find the code consistent with its own wrong understanding. Asking the same model again with a different prompt helps less than you would hope, because the underlying habits are the same.
A model from another family (Claude and GPT, in this repo) was trained differently and tends to fail on different things. Where one reviewer misses a boundary condition, the other often catches it. Where both raise the same finding, you can be more confident it is real. Where they disagree, the refute pass decides. That is exactly what scripts/cross-review.sh does: Codex reviews in a read-only sandbox, Claude Opus reviews in plan mode, and a third run tries to refute every finding from both and keeps only what survives, labelled with the model that raised it.
This costs more than one review, which is why the repo only requires it for the high-risk row of the Review levels table. For a medium-risk change one good reviewer plus the refuter is usually enough.
Leaderboards disagree. Run a 20-task eval on your own work.
Let me say this plainly: in November 2026 the public coding leaderboards do not agree with each other on which model is best, and the ranking changes every few weeks. They also measure tasks that are not yours, in repos that are not yours, without your review rules. I do not pick models from them any more.
What works better is a small personal eval. It takes an afternoon to set up and gives you numbers that apply to your codebase:
- Pick 20 closed tasks from your own history: merged pull requests or closed tickets that one agent run could reasonably do. Mix them: some bug fixes, some small features, a couple of refactors, a few that touch tests only.
- Write a definition of done for each, in the same style as the spec template: what must be true, checkable by a command or by reading one file. Usually this is “these tests pass” plus one or two specific behaviours.
- Start each run from the commit before the real fix, so every model gets the same starting point. A git worktree per task and per model keeps them apart.
- Run two or three candidate models on all 20 tasks with the same prompt. Part 4 gives you
scripts/agent-task.sh, which already runs one task headless with Claude Code or Codex, writes the summary and the result ofpnpm check, and (for Claude) logs the cost. - Score each run on three things: pass or fail against the definition of done; minutes you needed to review the result until you would merge it; cost in USD.
- Decide by role. The best executor is the cheapest model that passes most tasks with low review minutes. The best reviewer is the one that found the real problems in the failed runs without flooding you with false positives.
A plain spreadsheet with these columns is enough:
| Task | Model | Pass | Review minutes | Cost USD | Notes |
|---|---|---|---|---|---|
| T01 fix 404 on trailing slash | claude-sonnet-5-5 | pass / fail | … | … | … |
| T01 fix 404 on trailing slash | gpt-6.1-sol | pass / fail | … | … | … |
Review minutes is the column most people leave out, and in my experience it is the one that matters most. A model that passes slightly more tasks but produces diffs that take twice as long to read is not cheaper. Re-run the eval when a new model comes out; with the scripts in place it is mostly waiting time.
Check: see which model each agent role uses in the sample repo.
$ grep -n "^model" .claude/agents/*.md .codex/config.toml
.claude/agents/refuter.md:5:model: sonnet
.claude/agents/reviewer.md:5:model: opus
.codex/config.toml:5:model = "gpt-6.1-sol"
.codex/config.toml:6:model_reasoning_effort = "medium"
Claude Code and Codex in the same repo
The sample repo is set up for both Claude Code and Codex. That is not a hedge. They do different jobs well, and having both gives you the cross-family review for free. The key design decision is that the shared rules live in one place, AGENTS.md, and each tool’s own config holds only what is specific to that tool.
Codex reads AGENTS.md directly. Claude Code reads CLAUDE.md, and since it would only fall back to AGENTS.md when there is no CLAUDE.md, the repo’s CLAUDE.md starts by importing it:
CLAUDE.md
@AGENTS.md
## Claude Code
- For any feature, use the `implement-spec` skill. For a new idea without a spec, use `new-spec` first.
- Start non-trivial work in plan mode (Shift+Tab twice) and wait for approval of the task table.
- Before saying done, run the `reviewer` subagent on your diff, then the `refuter` subagent on its findings. Fix what survives.
- Hooks in `.claude/settings.json` format every edited file and block `git push`, `git add -A` and `rm -rf`. If a hook blocks you, do not work around it; tell the human.
- Personal overrides go in `CLAUDE.local.md` (git-ignored).
The Codex project config is short:
.codex/config.toml
# Project config for Codex CLI. Applies only when this project is trusted.
# Provider settings (model_provider, model_providers, profiles) are not allowed here;
# put them in ~/.codex/config.toml or a profile file. See examples/codex/.
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = false
Here is how the two compare, as configured in this repo:
| Aspect | Claude Code | Codex |
|---|---|---|
| Instruction file | CLAUDE.md, which starts with @AGENTS.md; personal notes in CLAUDE.local.md | AGENTS.md directly (global ~/.codex/AGENTS.md, then git root down to cwd; 32 KiB default cap) |
| Config file | .claude/settings.json (committed), .claude/settings.local.json (personal) | .codex/config.toml (trusted projects only), ~/.codex/config.toml, profile files like ~/.codex/deep-review.config.toml |
| Model in this repo | claude-opus-5-5 by default; sonnet for execution, opus for review | gpt-6.1-sol, model_reasoning_effort = "medium" |
| Sandbox / permissions | Permission rules allow / ask / deny (deny checked first), plus PreToolUse and PostToolUse hooks | sandbox_mode (read-only, workspace-write, danger-full-access), approval_policy, network_access = false |
| Guardrails in this repo | guard-bash.mjs blocks git push, git add -A, rm -rf; format-file.mjs formats every edit | Workspace-write sandbox without network; rules in AGENTS.md |
| Reusable workflows | Skills new-spec, implement-spec; subagents reviewer, refuter | Profiles, e.g. deep-review (effort high, read-only) |
| Headless command | claude -p "<prompt>" with --model, --permission-mode, --allowedTools, --max-turns, --max-budget-usd, --output-format json | codex exec "<prompt>" with --sandbox workspace-write, --json, -o |
| CI action | anthropics/claude-code-action pinned to v1.0.270 | openai/codex-action pinned to v1.13, permission-profile: ":read-only" |
| Review trigger | ai-review-claude.yml on every non-draft pull request; @claude comment via claude-mention.yml | ai-review-codex.yml on every non-draft pull request; @codex review comment via Codex cloud |
| Review rules source | “Code Review Rules” section of AGENTS.md, named in the prompt | ## Code Review Rules section of the nearest AGENTS.md |
The two models of control are different, and it helps to see them that way. Claude Code controls the agent mainly at the tool level: each tool call is checked against permission rules, and hooks can inspect or block it. Codex controls the agent mainly at the environment level: the process runs inside a sandbox that limits what it can write and whether it can reach the network. Both are useful. In this repo, Claude Code is the main interactive tool for planning and implementing, with its skills and subagents. Codex is the second family for review and a second executor for parallel tasks.
Note: both tools ignore project config until you trust the project. Codex applies .codex/config.toml only for trusted projects. Claude Code ignored all of .claude/settings.json, permissions and hooks, until I accepted the trust dialog; before that, a test git add -A went through. Part 2 shows how to set this up and test it.
A tour of the sample repo
The sample repo is agentic-shortlink, a small URL shortener API: Node 22, TypeScript (strict, ESM), Hono, SQLite via better-sqlite3, zod for validation, Vitest for tests, and Biome for lint and format.
What the app does
The whole API fits in one table, copied from the README:
| Method | Path | Notes |
|---|---|---|
POST | /api/links | body { url, slug?, expiresInDays? } -> 201, 400, 409 |
GET | /:slug | 302 to the URL; 404 unknown; 410 expired (spec 0001) |
GET | /api/links/:slug | stats: clicks, expiresAt, expired |
DELETE | /api/links/:slug | header x-api-key: $ADMIN_API_KEY -> 204 |
GET | /health | { "status": "ok" } |
Folder map
AGENTS.md gives every agent the same map of the code:
AGENTS.md
src/app.ts routes; all dependencies injected through createApp()
src/repo.ts LinkRepo, the only module that runs SQL
src/db.ts schema, created in openDb()
src/lib/ pure helpers with their own unit tests
test/ Vitest; test/helpers.ts gives makeApp() with an in-memory DB and a fake clock
docs/specs/ one spec per feature (NNNN-name.md); the spec is the source of truth
docs/tasks/ task breakdown for a spec, written by the planner
Around the app sits the agent setup, which is the real subject of the series:
| Path | Purpose | Series part |
|---|---|---|
AGENTS.md, CLAUDE.md | Shared instructions; Claude Code imports AGENTS.md | 2 |
.claude/settings.json, .claude/hooks/ | Permissions, guard hook, auto-format | 2 |
.claude/agents/ | reviewer and refuter subagents | 2, 4 |
.claude/skills/ | new-spec and implement-spec workflows | 3 |
.codex/config.toml, examples/codex/ | Codex project config, profiles, gateway provider | 2, 4 |
docs/specs/, docs/tasks/ | Spec template, spec 0001 (done), spec 0002 (exercise) | 3 |
scripts/agent-task.sh, scripts/cross-review.sh | Headless task in a worktree; two-family review | 4 |
gateway/litellm.config.yaml | One gateway for Anthropic, OpenAI, Gemini and local models | 4 |
.github/workflows/ | CI gate, Claude review, Codex review, @claude mentions | 5 |
Clone and run the gate
git clone https://github.com/luonghongthuan/agentic-shortlink
cd agentic-shortlink
corepack enable # gives you the pinned pnpm
pnpm install
pnpm check # lint + typecheck + tests
pnpm check is defined in package.json as pnpm lint && pnpm typecheck && pnpm test. It is the single command that every agent must run before saying it is done, and the same steps run in CI.
Check: the end of the output should look like this (timings will differ).
$ pnpm check
...
Test Files 2 passed (2)
Tests 13 passed (13)
On my machine the full check (lint, typecheck and 13 tests) runs in about a second; on a GitHub-hosted Ubuntu runner, the CI job takes about 24 seconds. If you want to try the API by hand, copy .env.example to .env, set ADMIN_API_KEY to 8 or more characters and run pnpm dev.
Note: on Windows with core.autocrlf=true, lint failed for me on CRLF line endings in the working tree. The repo ships a .gitattributes with * text=auto eol=lf; if you still see line-ending errors, run git config core.autocrlf false inside the repo and check out again.
Why the app is deliberately tiny
Five routes and one table is a small app on purpose. The series is about the workflow around the code, and a small app keeps the workflow visible. You can read all of src/ in ten minutes, so when an agent makes a mistake, you can see it. The full check runs in about a second, so the Verify step never becomes the bottleneck. And the features are small enough that one spec fits on a screen, which makes it easy to compare what different models do with the same spec.
Small does not mean trivial, though. The app has the things that make real reviews matter: input validation, a database, an admin route with an API key, time-dependent behaviour (link expiry), and a public response contract. Those are exactly the places where the Code Review Rules in AGENTS.md tell reviewers to look first.
What the next parts build
- Part 2, Repo setup: install Claude Code and Codex, write
AGENTS.mdandCLAUDE.md, permissions, hooks, subagents and Codex config, and test that they really apply. - Part 3, Spec, plan, tasks: use
new-specandimplement-specto turn spec 0002 into an approved task table. - Part 4, Parallel work and multiple providers: run tasks in parallel worktrees with
agent-task.sh, review withcross-review.sh, and put a LiteLLM gateway in front of every model. - Part 5, CI/CD with AI review: the CI gate, Claude and Codex review workflows,
@claudementions, and how to run them safely on pull requests. - Part 6, Operating it: cost limits, security, Dependabot for pinned actions, and the Learn step as a habit.
Common mistakes
One model plans, writes and reviews its own work
This is the most common setup and the weakest one. The review shares every misunderstanding the plan had. At minimum, review with a separate subagent that has a review-only prompt and no edit tools (the repo’s reviewer has Read, Grep, Glob, Bash and the instruction “You never edit files”), follow it with a refute pass, and for high-risk changes add a reviewer from another model family.
Picking models from a leaderboard
Leaderboards measure other people’s tasks and do not count your review time. They also disagree with each other. Twenty of your own closed tasks, scored on pass/fail, review minutes and cost, will tell you more than any public ranking.
Skipping the human gate on high-risk changes
Green CI and a clean AI review feel like enough. For schema, auth, workflows and dependencies they are not, because these changes are hard to reverse and the tests often do not cover what can go wrong. Automated changes to config are a good example: when I ran biome migrate on this repo, it rewrote "recommended": true to "preset": "none", which silently turned off every lint rule. CI stayed green, because there were no rules left to fail. Only reading the diff caught it.
No definition of done
Without one, the agent decides when it is finished, and it is usually optimistic. Every spec in the repo has a Definition of done where each line is checkable by a machine or by reading one file, and every task has its own Check command. If you cannot write that line, the spec is not ready.
Trusting config you have not tested
Rules in a file are not rules in effect. Claude Code ignored this repo’s permissions and hooks until the workspace was trusted. Write a small test for each guardrail (try a git add -A and watch it get blocked) before you rely on it. Part 2 does this step by step.
Checklist
- I can name the 7 steps of the loop and the two human gates.
- For each step I know who runs it, what artifact it produces and what ends it.
- My repo has a Review levels table (or I know where I will put one) with low, medium and high tiers.
- I have a model chosen for each role: planner, executor, primary reviewer, second-opinion reviewer from another family, router, and local model if I need one.
- I have listed 20 closed tasks for my own eval.
- I know which instruction and config files Claude Code and Codex read in this repo.
agentic-shortlinkis cloned andpnpm checkshowsTests 13 passed (13).
Series
- Architecture of an agentic workflow and choosing models by role
- Repo setup for Claude Code and Codex
- Spec, plan, tasks
- Parallel work and multiple providers
- CI/CD with AI review
- Operating it: cost, security, learning
- Part 7: Applying the agent workflow to a real project
This is part of the series Shipping software with AI agents, A to Z. All code is in the sample repo github.com/luonghongthuan/agentic-shortlink; clone it and follow along.

Discussion
Comments are reviewed before publication. Your email is kept private.