How I structure AI agents around ownership, testing, and review
What building ChartaFlow has taught me about making AI-assisted work easier to verify.
Start with a contract, not a prompt
ChartaFlow has an editor, public documentation, APIs, permissions, and a database. A seemingly small feature can touch several of them. I use a separate planning workspace to define the desired behavior, acceptance criteria, risks, and non-goals before sending work to a coding agent.
For a bug, I separate what I can observe from what I suspect. The handoff includes a reproduction path and the behavior that will prove the fix. The agent still has to inspect the current code; a planning document is context, not proof of implementation.
Give each agent a boundary
I configured eight specialized roles in Codex and Claude: an explorer, app worker, editor worker, API worker, database worker, public-docs worker, sysadmin worker, and independent reviewer. Each has a defined scope, constraints, and verification requirements.
The explorer stays read-only. Implementation agents own assigned files. If the editor worker needs an API change, it reports that dependency to the coordinator instead of editing across another worker’s assignment. Independent tasks can run in parallel; unresolved shared contracts stay sequential.
This makes the handoff concrete: what changed, where it changed, what was tested, and what remains uncertain.
Spend reasoning where a mistake matters
I use separate model and effort settings for each role. The explorer gets a lightweight model, bounded implementation uses medium effort, and database work and independent review receive deeper reasoning. The exact Claude and Codex defaults differ.
The rationale is to balance time and token use against the consequences of a mistake. It is a workflow choice, not a benchmark claim. A more capable model still needs tests and an independent check.
Explore the eight agent roles and model settings
Specialized agents, specific responsibilities
I’ve configured eight specialized agent roles in both Codex and Claude, with written instructions defining what each agent owns, which files it may change, what it must preserve, and how it should verify its work. A coordinating agent handles task routing, shared changes, and integration.
This is part of the project’s development workflow: a deliberate division of responsibilities that makes AI-assisted changes easier to review and coordinate.
Explorer: understand the system first
A read-only agent traces entry points, data flow, permissions, and dependencies before a task is assigned. It identifies the smallest relevant set of files and recommends an ownership split without changing the code.
Editor worker: protect the authoring experience
Focused on the TipTap editor: document state, JSON and HTML serialization, sanitization, and save/reload behavior. Its instructions require attention to how an editing change will affect published content, not just how it looks in the editor.
API worker: enforce server-side contracts
Handles assigned endpoints and domain logic, with explicit checks for input validation, authentication, project authorization, error handling, and sensitive-data exposure. For AI endpoints, its scope includes preserving rate, concurrency, and cost controls.
Database worker: make schema changes with evidence
Owns assigned forward migrations and database tests. It must preserve tenant isolation and row-level security, check both allowed and denied actions across applicable roles, and report any application changes needed to support the schema.
App worker: build the authenticated workspace
Works on the signed-in product interface outside the editor. It checks loading, empty, error, permission, and success states, while keeping UI changes separate from the API and database rules that enforce access.
Public docs worker: verify the reader’s experience
Handles public documentation routes, navigation, metadata, and rendering. Its boundaries explicitly protect draft content from public access and require compatibility with the HTML produced by the editor.
Sysadmin worker: isolate privileged operations
Focuses on administration surfaces with stricter authorization requirements. It must distinguish platform administrator access from ordinary project membership and check unauthenticated, non-admin, and authorized behavior.
Reviewer: challenge the finished change
An independent read-only reviewer inspects completed changes for authorization failures, data leaks, sanitization issues, AI cost-control regressions, and missing verification. It returns concrete findings for the implementation owner to fix rather than approving its own work.
Matching the model to the work
I’ve tuned each agent’s model and reasoning effort to its responsibility. My goal is to balance speed, token usage, and the consequences of a mistake: keep reconnaissance lightweight, give implementation enough room to reason, and reserve deeper analysis for database changes, privileged operations, and independent review.
The Claude and Codex configurations are separate choices for the same roles. Their effort settings are provider-specific; “medium” in one system isn’t a claim of equivalent compute or behavior in the other.
| Agent role | Claude model / effort | Codex model / reasoning |
|---|---|---|
| Explorer | Haiku · Low | GPT-5.6 Luna · Medium |
| App, editor, API, public docs | Sonnet · Medium | GPT-5.6 Terra · Medium |
| Database, independent reviewer | Opus · High | GPT-5.6 Sol · High |
| Sysadmin | Sonnet · Medium | GPT-5.6 Sol · High |
Reconnaissance: the explorer is read-only and returns a focused map of the code. A lightweight model keeps that first pass efficient; the Codex configuration still gives it medium reasoning effort to trace dependencies before implementation begins.
Bounded implementation: app, editor, API, and public-docs workers use medium effort with clear ownership and verification requirements. This is my practical default for keeping everyday development moving without spending the deepest reasoning budget on every edit.
Higher-consequence work: database changes and independent review use high effort because they need to examine permission matrices, migration effects, and failure paths. The Codex sysadmin worker also uses high effort for privileged operations; its Claude counterpart uses Sonnet at medium effort, with sensitive changes still subject to independent review.
Coordination: my Codex orchestrator uses GPT-5.6 Sol at low effort for routine routing and integration, while the specialized workers carry the deeper task-specific analysis. Model choice and thinking effort are separate controls, so I can tune both rather than treating one model as the answer to every task.
These are workflow defaults, not benchmark results or a guarantee of correctness. The rationale is to spend more reasoning where errors are harder to detect or more expensive to fix, while keeping tests, ownership boundaries, and independent review in place at every model tier.
Make verification repeatable
I added a disposable local Supabase harness to test real database policies, and a Playwright suite to exercise browser flows against isolated fixtures. The checks cover allowed and rejected actions, saving and publishing, checkpoint restoration, article movement, and recovery from partial failures.
Targeted commands let an agent check the affected domain during iteration. GitHub Actions runs the full verification suite, including the production build, database tests, and browser checks. Failure artifacts provide a starting point for diagnosis.
For changes that cross systems, I plan the actual initiating event and its failure paths. Testing a downstream metadata update is not equivalent to testing the operation that triggers it.
A concrete regression: stale publishing state
One regression involved the editor and navigation tree disagreeing about article metadata. The browser suite now checks that publishing uses the latest tree rename, move, and order rather than overwriting them with stale editor state.
Sharing page-persistence logic between those surfaces reduces duplicate behavior. The regression test captures the user-visible contract so later refactors have something specific to preserve.
Refine the workflow when the evidence changes
I maintain a repository routing map, scoped instructions, and shared domain guidance so agents can find the relevant context without loading everything. Type-checking hooks and Git safeguards add feedback around individual edits.
The aim is less rediscovery and more consistent handoffs. I haven’t measured a speed improvement. What I can point to is the implementation: clearer ownership, reusable verification, and regression coverage for failures the project has encountered.
See the ChartaFlow project ↗