The Production Coding Agent Workflow: Architecture, Verification, and Factual QA

A coding agent workflow is not a single prompt-and-response loop. Left to generate code in an unconstrained environment, agents suffer from context drift, hallucinated dependencies, and silent factual creep.

A production-grade coding agent workflow operates as a disciplined multi-stage control loop. It enforces strict boundaries between planning, code execution, deterministic test validation, and external factual verification.

The 10-Stage Production Coding Agent Lifecycle

[1. Intake & Scope Definition]
             │
             ▼
[2. Repo & State Inspection] ──> (Read-only environment discovery)
             │
             ▼
[3. Evidence & Constraints]  ──> (Identify ground-truth primary sources)
             │
             ▼
[4. Implementation Plan]     ──> [Human Review / Architectural Gate]
             │
             ▼
[5. Bounded Implementation]  ──> (Atomic, contiguous file edits)
             │
             ▼
[6. Deterministic Validation]──> (TypeScript, Linters, Test suites, Compilers)
             │
             ▼
[7. Factual QA & Source Gate]──> (Verify external claims against primary docs)
             │
             ▼
[8. Corrective Refinement]   ──> (Self-healing loop for factual or code errors)
             │
             ▼
[9. End-to-End Build & Diff] ──> (Clean tree check, full build pass)
             │
             ▼
[10. Atomic Delivery / PR]

Detailed Breakdown of Lifecycle Stages

Stage 1: Intake & Scope Boundary Definition

The workflow begins by establishing strict repository and directory boundaries. Agents must know what repositories they are allowed to modify and which external repositories or data directories are strictly read-only reference material. Without explicit boundary enforcement, agents risk modifying upstream dependencies or polluting local configurations.

Stage 2: Repository State & Dependency Inspection

Before proposing edits, the agent inspects existing conventions: package manager versions, test runners, framework versioning, and formatting rules. The agent maps out existing exports and internal libraries to avoid reinventing existing utilities.

Stage 3: Evidence Grounding & Constraint Identification

The agent gathers verifiable facts and constraints. Rather than guessing technical parameters, the agent inspects primary sources—official vendor documentation, schema definitions, or benchmark data files.

Stage 4: Implementation Plan & Human Review Gate

For non-trivial changes, the agent authors an explicit implementation plan detailing:

Exact files to be created, modified, or deleted.
Data structures and API schema adjustments.
Deterministic verification commands to be executed. This plan acts as an approval tripwire before files are modified on disk.

Stage 5: Bounded Implementation (Single Contiguous Slices)

The agent executes code changes in atomic, bounded chunks. Modifying small, contiguous blocks rather than rewriting entire files prevents accidental deletion of unrelated code, preserves existing docstrings, and minimizes merge conflicts.

Stage 6: Deterministic Validation Gates

Immediately following code modification, the agent executes local deterministic verification:

Type checking (tsc --noEmit)
Static linting (eslint, ruff)
Automated unit and integration tests (vitest, pytest)
Full production bundle builds (next build, cargo build)

Stage 7: Factual QA & Source Verification Gate

Even when Stage 6 passes cleanly, the agent must cross-examine user-facing assertions, configuration defaults, and documentation copy against the primary sources established in Stage 3.

Stage 8: Corrective Refinement Loop

If either deterministic tests fail or factual discrepancies are caught, the agent enters a corrective pass. It reads the exact error or documentation discrepancy, applies a targeted patch, and re-runs the validation sequence.

Stage 9: End-to-End Build & Clean Diff Verification

Before finalizing, the agent executes git diff --check and reviews git status to ensure no extraneous files, debug logs, or syntax formatting anomalies were introduced.

Stage 10: Atomic Delivery

The agent packages the validated changes into an atomic commit with an explicit commit message summarizing both the technical implementation and the verified evidence.

Empirical Case Study: The Limits of Deterministic Validation

To demonstrate why a distinct Factual QA gate is essential, consider a concrete first-hand case study from the CodexUsage codebase.

In this project, a developer tasked an agent with implementing a technical documentation page covering usage limits, reset cycles, and billing mechanics for OpenAI's gpt-6-astra model across ChatGPT Plus and Pro tiers.

Initial Implementation (Commit `a68c0bd8`)

In commit a68c0bd8882f81d2fcb71400f2d2d85fdc497307 ("feat(limits): add GPT-6 Astra usage limits page and internal links"), the agent generated a complete Next.js page component, updated routing paths, and configured internal navigation links.

The initial implementation was sufficiently complete to be committed, but code correctness alone did not guarantee factual accuracy. A subsequent factual review against current official OpenAI documentation revealed several material external-fact errors that normal code correctness checks would not detect:

Allowance Pool Terminology: The initial code claimed Astra drew from a generic "unified account pool." The official documentation specifies that Astra draws from an existing "Work and Codex allowance."
Subscription Tier Simplification: The initial code assumed ChatGPT Pro was strictly a single $200/month tier. In reality, OpenAI supports both Pro $100 and Pro $200 tiers, and states that Plus includes limited Astra usage while Pro $100 and Pro $200 can use their full existing allowance.
Omission of Fast Mode API Pricing: The initial implementation listed Platform API billing as standard token rates ($10/M input, $50/M output), omitting the official Fast mode rates ($20/M input, $100/M output).
Banked Reset Availability: The initial copy stated that ChatGPT Pro subscribers receive banked resets that can be manually triggered in settings. The official documentation clarifies that banked resets are promotional benefits whose eligibility and expiration depend on specific offers, plans, workspaces, and accounts.
Behavior at Allowance Ceilings: The initial code claimed that upon hitting a limit, Codex "completes the currently running turn before pausing." The official documentation specifies that an active turn continues subject to fair-use limits.
CLI Version Prerequisites: The initial code listed a minimum requirement of Codex CLI v0.153.1+, whereas official release notes confirmed compatibility from v0.153.0+.

The Corrective Commit (Commit `6759e5f6`)

In commit 6759e5f6e2f83ff8a4af7447872c85c66525c61e ("fix(limits): align GPT-6 Astra page with current official OpenAI docs"), a dedicated corrective pass updated the component text, comparison tables, and FAQ answers to align exactly with primary OpenAI source material.

Commit a68c0bd8: Initial Feature Implementation
  ├── Structural & Code Implementation: Committed to repository
  └── Factual Review against Primary Sources: Incomplete (contained allowance, pricing, and reset inaccuracies)
            │
            ▼
Commit 6759e5f6: Factual Alignment Pass
  ├── Code Adjustments: Updated UI copy, pricing tables, and limit descriptions
  └── Factual Verification: Verified against official OpenAI documentation

The Workflow Takeaway

Compilers and test runners verify structural integrity, not semantic truth. A coding agent that only runs automated code checks can commit code that is technically executable but factually false.

A production agent workflow must explicitly require the agent to audit every empirical claim, pricing tier, and service limit against official ground truth before code is deemed complete.

Context Management: Fresh vs. Continued Sessions

Context degradation is the primary cause of agent hallucinations during long tasks. Managing agent context requires disciplined boundaries:

Context Strategy	When to Use	Operational Mechanism
Continued Session	Incremental bug fixing, multi-step debugging, iterative refactoring within a single module	Preserve conversation history so the agent maintains awareness of compiler errors and previous attempts.
Clean / Fresh Session	Transitioning from planning to implementation, switching to an unrelated component, or launching a factual verification audit	Clear context completely and provide only the approved plan and target files. Prevents stale prompt instructions from biasing the new phase.
Hierarchical Subagents	Broad multi-file exploration, parallel research lookups, or documentation cross-checks	Spawn isolated, read-only subagents that report distilled findings back to the primary orchestrator without cluttering the main context window.

Best Practices for Production Coding Agents

Enforce Repository Read/Write Scopes: Explicitly instruct agents which repositories they may edit and mark reference repositories as strictly read-only.
Never Let Agents Self-Approve Factual Claims: When generating documentation, API guides, or product configurations, require the agent to cite primary sources in the commit record.
Require Atomic Git Verification: Run git status and git diff as an explicit tool step before committing to catch untracked scratch files and unintended edits.
Preserve Historical Metadata: When modifying existing files, preserve historical publication dates and record changes via structured changelog notes rather than falsifying creation dates.

Related Architecture and Verification Guides

Review the 8 applied subsystems governing AI agents and execution control loops

concept

Inspect our operational standards for evidence classification and verification integrity