Agentic Software Development#
Docs-as-code can be developed with conventional manual changes or with agent-assisted workflows. The key design rule is that agent assistance changes how changes are proposed and analyzed, not how merge eligibility is decided.
Lane A and Lane B#
Lane A is the deterministic path. It validates candidate behavior and evaluates change scenarios through the existing traceability gate. Lane A does not require an LLM.
Lane B is optional. A coding agent may inspect prior structured traces and propose improved harness candidates. Lane B can accelerate iteration, but it never overrides a Lane A denial.
This means:
manual and agent-assisted changes both converge on the same deterministic gate.
optional agent reasoning is kept outside the merge-critical decision path.
structured run artifacts are part of the design, not an afterthought.
Old approach vs harness-based approach#
Without the harness, repository checks can still validate a change, but the feedback surface is coarse: pass/fail results, scattered logs, and limited structured evidence for iterative improvement.
With the harness, changes are evaluated through a staged workflow:
cheap candidate validation first
deterministic task execution through the Lane A gate
distilled JSON trace artifacts for each task
append-only summary history for future comparison and learning
Old approach flow#
Harness-based flow#
Why the harness exists#
The harness adds a repeatable evaluation layer around docs-as-code change scenarios. It exists to make change quality visible in machine-readable form and make iterative improvement queryable over time.
The design goals are:
deterministic merge-critical checks
cheap rejection of malformed candidates
structured traces rather than raw stdout as the primary evidence format
selective navigation of prior runs through summary-first artifacts
optional agent-assisted improvement without introducing an LLM dependency into Lane A
For the implementation details, see Agent Harness.