AI / Agentic
One Coding Agent or Several? Follow the Shared Contract
By Vivek Jalondhara · 4 min read
Published
Choose agent count by task independence, using a source-reference change to explain coordination, handoffs, and integration evidence.
Several agents can produce several patches at once. Whether those patches form one correct feature depends on how much shared meaning they must preserve. Dividing work by frontend, backend, and tests can create parallel activity around a contract nobody has settled.
This illustrative Sheet Parser change adds a source reference to each extracted draft so a reviewer can open the original row. The feature is a design exercise. Its contract and coordination choices are not claims about the application's current implementation or agent usage.
Find the decision every contributor would need
The server, stored draft, and review interface all need to agree on what a source reference identifies. A row number without a sheet identifier is ambiguous. A sheet name without a source version can point at different content after a replacement upload.
Suppose the exercise chooses document revision, sheet key, and one-based source row as the reference. That decision must precede separate implementations. Otherwise one agent may count after header removal while another counts physical rows, producing individually reasonable code that highlights the wrong evidence when combined.
Use one implementer when the change is tightly coupled
A single bounded agent can follow the reference from validated extraction input through storage and rendering. Keeping the connected change in one working context reduces the number of places where that meaning must be summarized and rediscovered.
This is an argument about dependencies, not a claim that one agent is always faster or more accurate. Anthropic's guidance on effective agents recommends adding complexity when needed. For this example, begin with the smallest arrangement that can explain and verify the complete reference path.
Parallelize discovery where outputs remain independent
Independent work still exists. One investigator can inspect source-coordinate conventions in the document parser while another examines the review interface's navigation needs. Their outputs are findings and constraints, not competing mutations of the same schema.
Anthropic's research-system account describes both the value of parallel research and the coordination difficulties of tasks with shared context. Applying that distinction here, parallel exploration can inform the contract before an implementer changes code. The final decision still needs a named owner and a coherent rationale.
Make handoffs carry meaning, not just files
If separate implementation tasks become justified, give each a stable contract, a version, and a fixture with an expected source location. Include what happens when a reference is absent or outside the document. A type declaration alone cannot establish which coordinate convention it represents.
Ask each contributor to identify assumptions it could not verify and to avoid changing the shared contract silently. When the contract must change, revise dependent tasks together. A successful handoff is one another contributor can use without inventing missing semantics from a short completion message.
Reserve a complete integration check
Create a synthetic workbook in which two sheets both contain a row twelve but show different products. Import a candidate from one of them and open its evidence in the interface. This distinguishes a fully scoped reference from an implementation that accidentally uses the active sheet.
Also try a replaced source document and a missing reference. The application should explain the unavailable evidence instead of opening a plausible but unrelated row. Separate unit checks may all pass while this end-to-end meaning is broken, so task completion cannot be inferred by counting finished agents.
Choose the arrangement by reviewable outcomes
For a larger collection of independent adapters with a settled contract, several agents may be useful. For one evolving reference model, additional implementers may create more integration decisions than independent work. Reassess when the dependency structure changes rather than treating the initial agent count as permanent.
The tradeoff is possible parallel throughput against coordination and review effort. Track actual rework, conflicting assumptions, and the completeness of integration evidence if comparing approaches. Do not substitute the number of generated files or confident agent summaries for evidence that a reviewer can follow the correct source row.
A shared-contract handoff manifest
This JSON is a proposed coordination artefact rather than runtime configuration. It states the meaning of a reference and the integration witness that every implementation must preserve.
Illustrative example · JSON · Simplified for explanation
{
"task": "add source references to extraction drafts",
"contractVersion": 1,
"reference": ["documentRevision", "sheetKey", "sourceRow"],
"rowConvention": "one-based physical worksheet row",
"owner": "one implementation task",
"independentDiscovery": ["parser coordinates", "review navigation"],
"integrationWitness": "two sheets with different products at row 12",
"missingReference": "show evidence unavailable"
}- Map shared decisions
- Set the reference contract
- Delegate independent discovery if useful
- Implement the connected change
- Verify the complete evidence path
Conceptual flow for the example above.
Tradeoff to keep in mind
A manifest reduces ambiguity but cannot enforce coordination. The integrator must still inspect the combined result, and the proposed worksheet convention may not fit other document formats.