English | 中文
A bilingual methodology course on building complex software projects with AI coding agents — covering architecture decision records (ADR), operational runbooks, mechanical quality gates, capability-seam plugin architecture, microkernel design, and event-sourced state, distilled from the real-world deepseek-harness project.
This is a methodology course on how to bootstrap and continuously evolve a complex software project. It is distilled from a real, extreme case: deepseek-harness, a plugin-based agent harness developed primarily by AI coding agents, which went through 12,000+ commits, 226 workspace packages, and 720+ decision records in about two months without losing control.
You do not need access to the deepseek-harness repository to read this course. Every concept is explained self-contained; deepseek-harness appears only as case evidence. If you do want to verify a claim against its origin, Appendix A provides complete file-and-version traceability.
When development speed shifts from "humans write code" to "agents write code", the bottleneck is no longer output but consistency:
- Agents have no cross-session memory; yesterday's design rationale does not exist today;
- Agents infer unwritten rules from existing code, and the inference always skews more conservative than anyone intended;
- Code and tests record what changed, but not why this approach won or what was given up.
The methodology's answer is four externalizations: externalize memory into decision records, craft into operational procedures, discipline into mechanical gates, and architecture into a replicable extension pattern.
The same method works for purely human teams — it simply turns "what good teams used to maintain through tacit knowledge" into written institutions. Agents only make the cost of missing institutions show up faster.
| Chapter | Content |
|---|---|
| Chapter 1 Context and Problems | Three structural problems of agent-driven development |
| Chapter 2 Foundations: What to Do on Day One | World-view document, framework ownership, gates on day one |
| Chapter 3 Architecture Methodology | Microkernel, event semantics, capability seams, event sourcing, composition layers |
| Chapter 4 The Decision-Record System | How to design an ADR system that can actually be enforced |
| Chapter 5 Operationalizing Procedures | Turning recurring workflows into executable runbooks |
| Chapter 6 Mechanical Gates and Minimal Sufficient Evidence | CI owns the full matrix; locally, run only diff-relevant evidence |
| Chapter 7 Evolution Rhythm and Three Case Studies | Build-trim-archive; the full lifecycle of a frontend package |
| Chapter 8 Adoption Guide | Actionable checklists for day one, week one, and ongoing operation |
| Chapter 9 Pitfalls | Real traps and their remedies |
| Chapter 10 The rc.8 Case Study | Experimental-capability incubation, surface trimming, evidence-based CI tuning |
| Appendix A Traceability | Case data, concept sources, version anchors (optional reading) |
- To learn the method: read in order; every chapter ends with judgment criteria or adoption actions.
- To act: jump to the checklists in Chapter 8 and consult earlier chapters when a concept is unfamiliar.
- To verify: Appendix A maps every concept to files, dates, and versions in the deepseek-harness repository.
This course was written by Kimi K3 + Codex, with a human setting direction and making judgment calls.
The production process is itself an application of the Chapter 4 method — deconstruct first, then distill:
- Source study: starting from deepseek-harness's
.agentsdirectory, we read its decision records (720+), operational procedures (11), architecture docs, and full git history (12,000+ commits), reconstructing the project's build phases from filename dates and commit sequences; - Lifecycle tracing: we picked representative capability lines (the shell seam, the TUI's full lifecycle, Agent Teams' incubation in rc.8) and read their decision records chronologically to verify the methodology against real evolution;
- Distillation: observations were rewritten as self-contained chapters; the text paraphrases rather than quotes, and every judgment criterion can be traced in Appendix A to a specific decision record, date, and version;
- Fact verification: every file citation, version number, and statistic (package count, commit count, record counts) is mechanically checked, and updated as deepseek-harness releases (currently tracking
0.1.0-rc.8).
This repository practices what it teaches. Maintenance rules for contributors and agents live in AGENTS.md; the periodic update procedure — re-syncing against a newer deepseek-harness release — is maintenance/SYNC.md, backed by the mechanical gate node maintenance/verify.mjs.
The text of this course is an original methodological distillation. Case facts come from studying the deepseek-harness repository; sources are listed in Appendix A.
Keywords: AI coding agents, agent development methodology, architecture decision records (ADR), plugin architecture, microkernel, event sourcing, CI quality gates, minimal sufficient evidence, LLM agent harness, bilingual tutorial, deepseek-harness, AI 编程, agent 开发方法论, 架构决策记录, 插件化架构, 微内核, 事件溯源, 质量门禁, 中英双语教程