跪拜 Guibai
← All articles
Frontend · Backend · Interview

AI Coding's Real Bottleneck Is the Repository, Not the Model

By Moment ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Western teams adopting AI coding agents will hit the same wall: code gets easier to write, but repositories rot faster. Without a harness, agents amplify existing architectural debt, and human review becomes the queue that caps throughput. This is the missing engineering layer that determines whether agents accelerate a project or accelerate its decay.

Summary

Once coding agents like Codex, Claude Code, and Cursor Agent move beyond the novelty of rapid code generation, the bottleneck shifts to repository health. Agents produce code faster than humans can review, and they copy whatever patterns already exist—good or bad. Bad practices in the main branch become self-replicating templates. Stronger models and longer contexts patch symptoms; what's missing is a harness: the deliberate engineering environment around the agent.

The article lays out what that harness includes: a repository that acts as a readable engineering record system, an AGENTS.md that navigates rather than dumps all knowledge, deterministic checks (lint, hooks, structure tests, CI) for non-negotiable rules, observable evidence of completion, separation of short-term task state from long-term memory, and intentional backpressure when multiple agents flood PRs. When errors surface, the root cause must be written back into navigation, constraints, validation, or cleanup tasks so the next run starts from a better environment.

Harness Engineering is not a feature list or a thicker prompt file. It's a closed loop of context, implementation, constraint, verification, and feedback that turns one-off AI coding into a repeatable engineering discipline. Teams should start with a minimal feedback loop, not a full platform, and treat the harness—not the code—as the durable asset.

Takeaways
— The bottleneck in AI coding shifts from code generation to repository maintainability once agents are in daily use.
— Agents learn from existing repository patterns, so bad practices like cross-layer dependencies, generic helpers, and loose typings get copied and amplified.
— Engineering work moves from direct implementation to designing the environment: structure, navigation, automated checks, and validation paths.
— A harness is a closed loop covering navigation, implementation, constraints, verification, and merge judgment, with failure analysis written back into the system.
— Repositories must become engineering record systems storing code, Markdown, config, tests, logs, command results, and CI output.
— AGENTS.md should be an entry map that shortens the path from task to correct context, modification location, and verification commands, not an encyclopedia.
— Non-negotiable rules belong in deterministic mechanisms like lint, type systems, hooks, structure tests, and CI, not in reminders.
— Completion must be proven with observable evidence; the model's self-report is not enough.
— Long tasks need separation of temporary state, long-term memory, and mandatory gates; chat context alone won't hold multi-hour work.
— Multiple agents require deliberate backpressure; human review should focus on architecture and high-risk decisions, not machine-checkable issues.
— Errors should be traced to root causes and written back as rules, tests, docs, or cleanup tasks to prevent recurrence.
— AI coding without a harness generates code faster and amplifies existing repository problems. The harness is the team's durable asset.
Conclusions

Repository entropy is the real cost driver in AI coding; agents act as pattern amplifiers, so keeping main clean is more critical than model selection.

The distinction between prompt engineering, context engineering, skills, frameworks, and harness is not academic—conflating them leads teams to over-invest in AGENTS.md length and under-invest in deterministic checks.

Starting with a minimal feedback loop, as the article suggests, is a pragmatic counter to the platform-building reflex that often kills adoption of AI tooling.

The open question is whether small teams can sustain the discipline of writing back failure knowledge at the pace agents generate errors, or whether the harness itself becomes the new bottleneck.

Concepts & terms
Harness Engineering
The engineering discipline of building the environment around a coding agent—context, tools, memory, permissions, verification, and feedback loops—so that generated code remains controllable, verifiable, and maintainable in a real repository.
Application legibility and agent legibility
Properties OpenAI describes for harnesses: application legibility means the repository is structured and documented so an agent can understand it; agent legibility means the agent's actions and state are observable to humans for review and control.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗