How I steer AI development toward a defined outcome
The planning, architecture, ownership, and verification system I use to direct AI-assisted development in ChartaFlow.
Define the task before assigning it
ChartaFlow has an editor, public documentation, APIs, permissions, and a database. A small feature can affect 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.
Build a context flywheel
A good prompt is temporary. The repository needs durable context that survives the task. I designed the workflow to capture verified outcomes and failures automatically, then route lasting lessons into the appropriate source of truth: product requirements, current architecture, security boundaries, agent orchestration, or area-specific implementation rules.
That creates a feedback flywheel rather than a pile of static instructions. A routing map connects product areas to their code paths, data, dependencies, tests, and assigned agents. New work loads the relevant context, verification tests it against real behavior, and durable findings strengthen the next task.
Current code and database migrations remain the final evidence. If the documentation disagrees with them, the agent must inspect the implementation and correct the relevant document as part of the change.
Set clear ownership
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.
Each handoff lists the files changed, tests run, dependencies, and remaining uncertainty.
How a change moves through the system
The coordinator assigns work by ownership, keeps shared changes sequential, and brings the results back together for review. Failed checks return to the agent that owns the affected area.
flowchart TB
A[Define outcome and acceptance criteria] --> B[Map dependencies, risks, and ownership]
B --> C[Coordinator assigns bounded tasks]
subgraph AGENTS["SPECIALIZED AI AGENTS"]
direction LR
D1[Explorer
Read-only system map]
D2[App and editor agents
User experience and state]
D3[API and database agents
Contracts, auth, and RLS]
D4[Public docs and sysadmin agents
Publishing and privileged operations]
end
C --> D1
C --> D2
C --> D3
C --> D4
D1 --> E[Coordinator integrates changes]
D2 --> E
D3 --> E
D4 --> E
E --> F[Targeted checks
Types, unit tests, database, browser]
F --> G{Checks pass?}
G -- No --> H[Return findings to the owning agent]
H --> E
G -- Yes --> I[Independent review]
I --> J{Issues found?}
J -- Yes --> H
J -- No --> K[Preview deployment and route checks]
K --> L[Production release and live verification]
classDef agent fill:#6254c7,color:#fff,stroke:#41368f,stroke-width:3px
classDef coordinator fill:#dce4ff,color:#20233a,stroke:#5368c7,stroke-width:2px
classDef review fill:#dff3e9,color:#173c2c,stroke:#4d8c70,stroke-width:2px
classDef gate fill:#fff1d7,color:#49330e,stroke:#b7832f,stroke-width:2px
class D1,D2,D3,D4 agent
class C,E coordinator
class I review
class G,J gate
style AGENTS fill:#f2f0ff,stroke:#7567d5,stroke-width:2px
Match reasoning effort to risk
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.
I balance time and token use against the cost of a mistake. This is a workflow choice, not a benchmark claim. A more capable model still needs tests and an independent check.
View agent roles and model settings
Agent roles and 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.
The role boundaries make changes easier to assign, review, and integrate.
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.
Model and reasoning settings
I’ve tuned each agent’s model and reasoning effort to its responsibility. I keep reconnaissance lightweight, use medium effort for bounded implementation, 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.
Run repeatable checks
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.
Example: 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.
Turn failures into system memory
The automated workflow records durable findings in the repository routing map, scoped instructions, shared domain guidance, and regression coverage. Agents can find the relevant context without loading everything, while type-checking hooks and Git safeguards add immediate feedback around individual edits.
When a failure reveals a weak assumption, the workflow feeds the lesson back as a durable rule, test, or safeguard. Reliability compounds: the system retains what was learned, applies it to future work, and verifies that the same class of failure does not quietly return.
See the ChartaFlow project ↗