Claude Code 工程工作流指南

English | 中文

---

背景故事

我用 Claude Code 做了一个中型 Web 应用。一开始很随意：想到什么就让 CC 写，写完就交。结果两周后发现代码越来越难改，测试为零，每次新会话都要重新解释项目上下文。

于是我花了几天时间建立了一套工程纪律：先写清楚要做什么再动手（Spec Coding）、先写测试再写代码（TDD）、每次提交必须过覆盖率门禁、所有决策必须记录。这些纪律看起来"慢"，但实际上让我后续越做越快——上千个测试成了安全网，覆盖率门禁挡住了无数低级错误，CHANGELOG 让每次新会话都能快速恢复上下文。

这套工作流让我在几个月内完成了多次大版本迭代，测试覆盖率从约 75% 稳步提升到近 90%，最关键的是：0 次重大回滚。没有哪次改动让我"改不动了只能推倒重来"。

我把这些实践提炼成这个仓库，分享给同样用 CC 做开发的你。不是教条，是踩过坑之后发现真的有用的东西。

---

这是给谁的

• 刚从传统 IDE 切换到 Claude Code，想知道怎么和 CC 高效协作的开发者
• 用 CC 写代码但工作流比较随意，想建立纪律但不从零造轮子的开发者
• 带团队使用 CC，想统一工程规范的技术负责人
• 对 AI 编程工程化感兴趣，想看看别人怎么做的开发者

怎么用

根据你当前的状态选择：

场景 A：全新项目

从头搭建，直接用模板：

1. 复制 templates/CLAUDE.md 到项目根目录，填写项目定位和架构决策
2. 复制 templates/testing_policy.md 到 docs/
3. 复制 scripts/run_coverage.py 到 scripts/（Python 项目，其他语言参照 03 文档实现）

场景 B：已有项目，想增量采纳

不需要一次性搬所有模板。按优先级逐步引入：

第 1 步（10 分钟）：在你的 CLAUDE.md 中添加核心段落。对照 templates/CLAUDE.md，把缺失的段落补上：

• 交付门禁（6 条规则，防止 Agent 假完成）
• 覆盖率目标（分层目标 + 门禁命令）
• 安全底线（改动前后必须 commit）

第 2 步（5 分钟）：添加 CHANGELOG 习惯。参照 templates/changelog-entry.md 的格式，下次迭代结束时写一条 CHANGELOG。

第 3 步（15 分钟）：设置覆盖率门禁。参照 docs/03-testing-and-gates.md 中你的语言对应的方案。

第 4 步（按需）：引入其他工具——设计文档模板、代码索引、知识记忆，按需添加。

场景 C：只是想了解工作流思路

读一遍四篇文档就够了，不需要复制任何文件：

文档	解决什么问题	阅读时间
01-project-scaffold.md	项目目录怎么组织，CLAUDE.md 怎么写	5 分钟
02-dual-session-workflow.md	两个会话怎么分工，交接物是什么	8 分钟
03-testing-and-gates.md	TDD 怎么落地，覆盖率门禁怎么设（多语言）	8 分钟
04-documentation-system.md	CHANGELOG、设计文档、知识记忆怎么维护	5 分钟

前置条件

• 本仓库附带的门禁脚本为 Python 版本，运行需要 Python 3.8+ 和 pip install pytest pytest-cov。其他语言参照 03-testing-and-gates.md 中的方案实现
• 项目使用 app/models/ + app/services/ + app/api/ 目录结构（可自定义，见 03-testing-and-gates.md）
• 基本了解 TDD、覆盖率、pre-commit hook 概念

模板文件

文件	用途
templates/CLAUDE.md	项目级配置模板（开发流程 + 测试 + 安全底线）
templates/testing_policy.md	测试策略文档模板
templates/design-doc.md	设计文档模板（含决策矩阵）
templates/changelog-entry.md	CHANGELOG 条目格式
templates/memory-entry.md	知识记忆条目格式

许可

MIT

---

Claude Code Engineering Workflow Guide

English | 中文

---

Background Story

I built a medium-sized web application with Claude Code. At first I was casual: tell CC what to write, submit when done. Two weeks in, the code was getting harder to change, I had zero tests, and every new session required re-explaining the entire project context.

So I spent a few days establishing engineering discipline: write specs before coding (Spec Coding), write tests before implementation (TDD), enforce coverage gates on every commit, and document every decision. These practices felt "slow" at first, but they actually made me faster over time — thousands of tests became a safety net, coverage gates caught countless bugs, and CHANGELOGs let every new session recover context instantly.

This workflow helped me ship multiple major versions over several months, steadily increase test coverage from ~75% to nearly 90%, and most importantly: zero major rollbacks. No change ever left me thinking "this is unfixable, I need to start over."

I've distilled these practices into this repo for fellow CC developers. Not dogma — just things that actually worked after learning the hard way.

---

Who Is This For

• Developers new to Claude Code who want to collaborate effectively with an AI coding agent
• CC users with ad-hoc workflows looking for battle-tested practices
• Tech leads adopting CC across a team who need consistent engineering standards
• Anyone curious about AI coding engineering practices

How to Use

Choose based on your situation:

Scenario A: New Project

Start from scratch with templates:

1. Copy templates/CLAUDE.md to your project root, fill in project description and architecture decisions
2. Copy templates/testing_policy.md to docs/
3. Copy scripts/run_coverage.py to scripts/ (Python projects; for other languages, see doc 03)

Scenario B: Existing Project, Incremental Adoption

Don't need to adopt everything at once. Introduce practices incrementally:

Step 1 (10 min): Add key sections to your existing CLAUDE.md. Reference templates/CLAUDE.md and add missing sections:

• Delivery gate (6 rules to prevent AI agent false completions)
• Coverage targets (layered targets + gate command)
• Safety baseline (commit before and after major changes)

Step 2 (5 min): Start the CHANGELOG habit. Use templates/changelog-entry.md format for your next iteration.

Step 3 (15 min): Set up coverage gates. See docs/03-testing-and-gates.md for your language's approach.

Step 4 (As needed): Adopt other tools — design doc templates, code indexes, knowledge memory.

Scenario C: Just Exploring

Read the four docs, no file copying needed:

Doc	What It Covers	Read Time
01-project-scaffold.md	Project structure and CLAUDE.md setup	5 min
02-dual-session-workflow.md	Dual-session workflow and handoff artifacts	8 min
03-testing-and-gates.md	TDD, coverage gates (multi-language)	8 min
04-documentation-system.md	CHANGELOG, design docs, knowledge memory	5 min

Prerequisites

• The included coverage gate script is Python-based, requiring Python 3.8+ and pip install pytest pytest-cov. For other languages, see 03-testing-and-gates.md
• Project directory structure like app/models/ + app/services/ + app/api/ (customizable, see 03-testing-and-gates.md)
• Basic understanding of TDD, code coverage, and pre-commit hooks

Template Files

File	Purpose
templates/CLAUDE.md	Project-level config template (dev flow + testing + safety)
templates/testing_policy.md	Testing strategy template
templates/design-doc.md	Design document template (with decision matrix)
templates/changelog-entry.md	CHANGELOG entry format
templates/memory-entry.md	Knowledge memory entry format

License

MIT