Claude高质量产出

Claude分层分模块产出

1) 总体原则：把"写代码"改成"生成受控变更"

复杂项目里模型失控的本质是：它在一次对话里同时承担了需求澄清、架构设计、接口定义、实现、测试、联调，上下文必然爆炸，且不可验证。

落地做法是把交互强制切成四层产物，并且每层都有"冻结点"：

产品层（PRD/用户故事）冻结：模型只能改文档，不写代码
系统设计层（模块/接口/数据）冻结：模型只能改设计，不写代码
任务层（按模块拆成小任务）冻结：每个任务可在 1~3 个文件内完成
实现层（代码变更集）：每次输出必须是可审查的 diff / 文件清单

要做的不是让模型"理解全部"，而是让它永远只处理一个"最小闭环任务"。

2) 文档分层：用"从上到下的约束"压住上下文

给你一个可直接复制使用的文档结构（建议放在仓库根目录 /docs，并要求模型只能引用这里的内容）。

2.1 L0：一页项目宪法（Project Charter，强约束）

文件：docs/00_charter.md（1 页内）

目标/非目标（Non-goals 很重要）
核心名词表（术语统一，减少"需求不清楚"）
成功指标（可验证）
技术栈与硬约束（语言/框架/部署环境/兼容性）
关键决策记录（ADR 链接）

用法：每次让模型开始任务前先贴这份（或让模型只读摘要），确保一致性。

2.2 L1：PRD 分模块（按业务域拆）

文件：docs/prd/*.md

每个 PRD 最好覆盖一个业务域（例如：用户、订单、支付），每个文件包含：

用户故事（Given/When/Then 或场景流）
主要流程（文字 + 简单流程图）
数据需求（字段、约束、校验、权限）
异常与边界
验收标准（Acceptance Criteria）

用法：你只把"本次要改的模块 PRD"给模型，而不是整个 PRD 大全集。

2.3 L2：系统设计（模块/接口/数据契约）

文件：

docs/design/architecture.md（全局架构图 + 模块边界）
docs/design/modules/<module>.md（每模块一份）
docs/design/api/<service>.yaml（OpenAPI/Proto/JSON Schema）
docs/design/data/<domain>.md（ERD/表结构/索引/约束）

重点：接口契约优先（先定义输入输出与错误码），代码只是契约的实现。

2.4 L3：任务拆解（面向实现的最小任务）

文件：docs/tasks/

每个任务一张卡（类似 Jira ticket），必须包含：

任务目标（一句话）
变更范围：文件清单（预计改哪几个文件，越少越好）
前置条件/依赖
测试策略（至少一条可执行验证方式）
完成定义（DoD）

3) 图结构表达：让模型"看见边界"，减少错误联想

"过大的代码结构"时，纯文本描述会让模型在脑内补全大量不存在的东西。解决方式是强制图结构化，让它只能在边界内推理。

3.1 依赖图（模块级）

用 Mermaid 存在 docs/design/architecture.md：
Web/UI
API Gateway
User Service
Order Service
Order DB
User DB
Message Queue

3.2 模块责任卡（Module Responsibility Card）

每个模块一段固定模板（写在 docs/design/modules/<module>.md）：

负责什么（Responsibilities）
不负责什么（Non-responsibilities）
公开接口（Public APIs）
数据拥有权（Owner of data）
依赖（Dependencies）
性能/一致性要求

这能显著减少模型"跨模块乱改"或"引入不必要耦合"。

3.3 数据流图（关键链路）

对关键业务链路（如下单）画 DFD 或时序图，帮助模型不丢步骤。

4) 上下文过长的工程化解法：建立"上下文包 Context Pack"

不要把整个 repo 粘给模型，而是每次给一个"上下文包"，内容固定、可控、可复用。

4.1 Context Pack 标准结构（建议 1~3 页）

本次目标（1 段）
相关模块边界（链接到模块卡）
相关接口契约（OpenAPI/Schema 的关键段）
需要读取的文件列表（最多 5~8 个）
禁止触碰的区域（例如：不要改数据库迁移/不要改公共库）
验收标准（3~10 条）

你可以把它做成：docs/context/<feature>.md。

4.2 输入策略：只提供"索引 + 必要片段"

当代码结构很大时，先让模型输出"需要哪些文件"清单，你再分批提供：

Repo Map（索引）：目录树 + 每个包的一句话职责
目标模块文件：只给任务涉及的那几份
契约文件：OpenAPI/Proto/Schema
现有测试：相关测试用例

关键：模型第一次不要写代码，先给"文件读取计划 + 变更计划"。

5) 分模块设计到代码：用"契约驱动 + 垂直切片"

大项目最容易失败的是"横向改一大片"。可落地的方式是：

5.1 契约驱动（Contract-first）

顺序固定为：

定义 API/事件/DTO（schema）
定义错误码与边界条件
定义测试用例（至少单测/契约测试）
再实现

让模型输出时必须先改契约文件，再改实现文件。

5.2 垂直切片（Vertical Slice）

一次只做一个端到端的小闭环：

例如"创建订单"闭环包含：

一个 endpoint
一个 usecase/service
一个 repository 调用
对应测试
必要的最小 UI/CLI（可选）

禁止一次性"把订单模块全补齐"。

6) 让输出可控：强制"分阶段输出格式"

给模型固定输出协议（你可以直接用作提示词模板）：

阶段 A：澄清与计划（不写代码）

我理解的需求（≤10 条）
未决问题（≤5 条，必须是阻塞性的）
影响范围（模块/文件）
实施步骤（3~7 步）
风险点与回滚策略

阶段 B：设计产物（先文档后代码）

更新哪些设计文档（列出文件名 + 变更摘要）
接口/数据契约变更（diff 或片段）
测试计划

阶段 C：代码变更集（严格限制）

变更文件列表（新增/修改）
每个文件的变更点摘要
代码 diff（或逐文件完整内容，但不混在解释里）
新增/更新测试与如何运行

如果模型一次输出太多，你要求它"只输出文件清单 + diff 片段"，分批提交。

7) 对"结果不符合预期"的闭环：用验收标准和可执行检查

不要用"感觉不对"，要把预期变成可执行的检查：

PRD 的每条 Acceptance Criteria 都映射到：
- 一个测试用例（单测/集成测试/契约测试）
- 或一个脚本命令（curl / postman collection / e2e）
让模型在输出最后必须附带：
- 如何验证（命令 + 预期输出）
- 回归影响（哪些功能要回归测）

8) 最小落地方案（你今天就能开始用）

如果你不想一下子建很多文档，先做"三件套"，基本就能显著改善：

docs/00_charter.md：项目宪法（1 页）
docs/design/architecture.md：模块图 + 每模块责任边界（Mermaid）
docs/tasks/TASK-xxx.md：每次只做一个小任务卡（含文件范围+验收）

然后你每次与模型交互都遵循：

先让它基于 TASK 输出计划
再让它生成/更新设计片段
最后才写代码，并限制文件数

9) 你可以直接复制的"任务卡模板"

md 复制代码

## TASK-xxx: <一句话目标>

### 背景/目标
- ...

### 范围（必须小）
- 修改：a/b/c.ts
- 修改：x/y/z.ts
- 新增：...

### 非目标
- ...

### 需求/验收标准（可测试）
1. Given ... When ... Then ...
2. ...

### 设计约束
- 接口契约：docs/design/api/xxx.yaml
- 模块边界：docs/design/modules/xxx.md

### 实施步骤（建议）
1. ...
2. ...

### 测试与验证
- 单测：...
- 集成：curl ...
- 回归：...

传统软件工程 vs Claude 类大模型编码（不同策略）复杂度对比评估（按规模/模块/分布式分级）

目标：用可复核的工程事实 来对比"传统软件工程"和"Claude 类大模型编码"在不同使用策略下，可稳定支撑的软件复杂度范围。

方法：以工程界常用的复杂度代理指标（代码行数/模块数/服务数/单次变更触达范围 ）做分级，并用可引用的证据 解释边界来源（而不是拍脑袋给结论）。

注：LOC 本身不是复杂度的充分指标，但在与模块数/分布式程度/变更范围结合后，可以作为粗粒度分级依据。

1. 复杂度分级（从单文件到分布式）------工程上常见的"规模阶梯"

下面的分级来自工程实践中对系统形态的常见划分：单文件脚本 → 小型应用 → 中型单体 → 大型单体/模块化单体 → 多服务系统 → 大规模分布式。每一档给出可衡量特征（LOC/模块/服务/变更范围）。

级别	系统形态	典型规模（可量化特征）	典型工程活动
L0	单文件/少文件脚本	1--5 文件；<1k LOC；0--2 个外部依赖包	直接修改、几乎不需要架构
L1	小型应用（单仓库）	10--50 文件；1k--10k LOC；模块/包 5--20	开始需要目录结构、简单测试
L2	中型单体（清晰分层）	10k--100k LOC；模块 20--80；单进程部署	需要明确分层、CI、回归测试
L3	大型单体/模块化单体	100k--500k LOC；模块 80--200；多个子系统	需要架构治理、依赖规则、平台化测试
L4	多服务系统（微服务/分布式）	服务 5--30；每服务 10k--200k LOC；跨服务 API/消息	契约、版本治理、可观测性、发布编排
L5	大规模分布式/平台级	服务 30+；多团队、多仓库；复杂一致性与容灾	严格变更管理、SRE、混沌工程、强合规

这些阈值不是"标准"，但它们对应了组织/流程/架构必须升级的节点：例如从 L2→L4，复杂度主要来自分布式一致性、契约治理和发布编排，而不是 LOC 本身。

2. "不凭空猜测"的依据：上限来自哪里（传统工程 vs LLM）

2.1 传统软件工程为何能到 L4/L5（证据类型：组织与流程可持续性）

传统工程的可扩展性来自：

模块化与信息隐藏（Parnas 1972 的经典观点：通过模块边界控制复杂度）
分层架构、接口契约、变更控制、代码评审、测试金字塔、CI/CD
把"全局一致性"交给流程与角色（架构师/Owner/评审/发布经理/SRE），而不是单个个体的短时记忆

这不是理论：行业长期存在大量 L4/L5 系统（电商、支付、广告、云平台）在多年迭代中保持可用性，说明传统工程的上限主要由组织工程能力决定，而非工具硬限制。

2.2 常规 LLM 编码为何容易卡在 L1~L2（证据类型：模型机制 + 实证研究方向）

LLM 受限点主要不是"不会写"，而是：

长上下文一致性与检索能力在长度增加时下降（大量研究讨论 long-context 的检索/引用退化与"lost in the middle"等现象；工程上普遍用 RAG/索引+分解缓解）
无法天然持有系统级不变量（鉴权一致性、跨服务幂等、错误码规范、领域约束），除非这些被外化为契约/测试/门禁
大范围改动缺少可靠验证闭环：传统工程用 CI、回归、契约测试来约束；常规"贴需求→出代码"通常缺这套约束

结论：LLM 常规用法的"复杂度上限"常体现为：一旦单次变更触达范围增大（跨模块/跨服务/多文件），错误率与返工上升。这与传统工程里"变更规模越大风险越高"的经验规律一致，只是 LLM 会更快触发这一拐点。

3. 对比对象定义（3 种方式）

为避免空泛，固定三种实践方式：

传统软件工程（TSE）：人主导需求/设计/实现/测试；LLM 仅作搜索/补全（不改变流程核心）。
Claude 常规用法（LLM-Base）：对话式贴需求、贴部分代码，模型直接给实现；文档/契约/测试不是强制门禁。
Claude 工程化用法（LLM-Eng，包含"优化"核心） ：
- 分层文档（Charter/PRD/模块卡/契约/任务卡）
- RepoMap + 索引检索/RAG（只取相关上下文）
- 变更以 diff/PR 为单位，小步提交
- 强 CI 门禁（类型检查、lint、单测、契约/集成测试、安全扫描）
- ADR/依赖规则守护（防止架构漂移）

4. 核心评估指标：用"单次变更触达范围"连接 LOC/模块/分布式

为什么要看"单次变更触达范围"？因为它是可复核的风险代理指标：在任何代码库里你都能统计：

一次 PR 改了多少文件（files changed）
涉及多少目录/模块/包
是否跨服务/跨仓库
churn（新增/删除行数）

传统工程的许多风险模型（业界常用）都把 churn、文件数、模块数作为缺陷风险特征之一。对 LLM 更关键：模型一次对话/一次生成最容易失控的就是"触达范围太大"。

5. 分级对比表（从 L0 到 L5）：能否"稳定交付与长期演进"

下表给出每一复杂度级别，三种方式的可行性、关键约束、需要的工程措施。这里不靠"猜测某种 LOC 上限"，而是把差异落到可验证的工程手段与风险点上。

L0：单文件脚本

项目特征	TSE	LLM-Base	LLM-Eng
1--5 文件、<1k LOC	可行且稳定	可行，速度优势明显	可行，但工程化收益不大
关键风险	很低	幻觉/边界遗漏	过度流程化
建议	无	最好给清晰输入输出	同 Base

L1：小型应用（1k--10k LOC，模块 5--20）

项目特征	TSE	LLM-Base	LLM-Eng
单仓库、小团队	稳定	通常可行；但需求稍复杂就会"跑偏"	稳定，迭代更快
主要差异点	人能靠直觉保持一致性	容易在边界条件、错误处理、权限上漏	用任务卡/契约/测试把"漏"变成可检出
必要措施	基础测试+CI	至少要求模型输出测试	强制小步 PR + 单测

L2：中型单体（10k--100k LOC，模块 20--80）

项目特征	TSE	LLM-Base	LLM-Eng
分层/模块化开始重要	稳定（依赖评审+测试+架构约束）	风险显著上升：上下文开始不够用，跨模块修改易引入回归	可稳定，但必须"模块卡+契约+拆任务"
关键拐点（可观测）	PR 跨模块变更仍可控	PR 文件数上升 → 模型遗漏约束、重复造轮子、架构漂移	通过"影响范围限制+检索上下文"减轻
必要措施	依赖规则、测试金字塔	最少：要求模型先做变更计划	RepoMap/RAG + 强 CI

L3：大型单体/模块化单体（100k--500k LOC，模块 80--200）

项目特征	TSE	LLM-Base	LLM-Eng
子系统众多、耦合治理关键	可行，但需要架构治理（依赖约束/平台化测试/组件化）	通常不可持续：模型对全局不变量与依赖规则难以长期一致	可行，但"工程化成本"必须上来
关键风险	架构债、组织协作	大范围改动 + 长上下文 → 不一致与回归	检索错误/上下文包不准仍会出问题
必要措施	架构评审、模块 owner	不建议用 Base 推进主干	ADR+依赖lint+门禁测试+分层文档

L4：多服务分布式（服务 5--30，跨服务 API/消息）

项目特征	TSE	LLM-Base	LLM-Eng
分布式一致性、发布编排、可观测性	可行（成熟团队可到很大规模）	高概率失败：跨服务契约、版本兼容、灰度发布等不是"写代码"能解决	可行，但要求"契约治理 + 自动化回归 + 发布策略"齐全
关键拐点（可观测）	契约变更需要兼容策略	Base 模型极易改 A 忘 B，或破坏兼容	用 OpenAPI/Proto + 契约测试锁住行为
必要措施	契约测试、SRE、监控回滚	Base 不适配	契约优先 + 影响分析 + 多环境验证

L5：大规模分布式/平台级（服务 30+，多团队）

项目特征	TSE	LLM-Base	LLM-Eng
多团队并行、合规、安全、容灾	可行（但成本高）	基本不可持续	在"平台工程成熟"的前提下可行；LLM 提升局部吞吐，但不减少治理需求
关键风险	变更治理与可靠性	同 L4 且更严重	RAG/自动化/门禁维护成本高
必要措施	严格变更管理、SLO、混沌工程	不建议	平台化CI/CD + SLO门禁 + 安全合规扫描

6. 用"可度量的门槛"把结论落地（你可以在仓库里直接统计）

下面给出三类方式在不同复杂度下，最关键的可量化门槛（这些都能从 Git/CI 里取数）：

6.1 变更触达范围门槛（每个 PR/任务）

LLM-Base 推荐门槛 ：
- files changed ≤ 5
- 涉及模块 ≤ 1
- 无跨服务契约改动
  一旦超过，失败率（返工、漏需求、回归）会显著上升（原因见 2.2：上下文与一致性问题）。
LLM-Eng 可提高门槛的前提 ：
- 有契约文件（OpenAPI/Proto/Schema）+ 契约测试
- 有 RepoMap/RAG（模型只拿相关上下文）
- 强 CI 门禁
  这时单 PR 可以覆盖更多文件/模块，但仍建议拆分为可验证的垂直切片。

6.2 "架构漂移"可检测信号

无论是否用 LLM，漂移都能通过以下指标观测：

循环依赖数量上升（依赖图/静态分析可得）
公共层/工具层膨胀（通用 helper 激增）
跨层调用比例上升（例如 UI 直连 DB、domain 依赖 infrastructure）
同类功能重复实现（重复 DTO、重复校验逻辑）

LLM-Base 更容易触发这些信号；LLM-Eng 用"模块责任卡 + 依赖规则 lint + ADR"来抑制。

6.3 分布式系统的"硬门槛"：契约与兼容

到了 L4/L5，复杂度的核心不再是 LOC，而是：

API 版本兼容策略（向后兼容、灰度、双写/双读）
幂等、重试、超时、熔断
观测（trace/metrics/log）与回滚机制
这些必须通过文档+自动化测试+发布流程固化；LLM 只能加速实现，不能替代治理。

7. 结论（按"从单文件到分布式"的可持续上限）

传统软件工程：从 L0 到 L5 都可达，上限主要由组织工程能力与治理投入决定。
Claude 常规用法（LLM-Base）：在 L0--L1 通常稳定；到 L2 开始明显依赖任务切小；L3+ 很难长期不漂移；L4/L5 基本不具备可持续性（除非回到传统工程治理）。
Claude 工程化用法（LLM-Eng） ：通过把需求/架构/契约/测试外化并门禁化，可在 L2--L4 稳定推进，甚至触达 L5 的部分场景；但前提是平台化工程投入到位（索引检索、CI、契约治理、发布与可观测）。

8. 参考与"凭据类型"（便于你向团队/管理层交付）

为保证"有依据"，这里列出支撑本文关键论点的可引用来源类型（你可按需要补充具体文献/内部数据）：

模块化与信息隐藏 ：David Parnas, On the Criteria To Be Used in Decomposing Systems into Modules (1972) ------ 支撑"边界/契约控制复杂度"。
长上下文检索退化/中间信息丢失（lost-in-the-middle）：多篇关于长上下文注意力与检索的研究与评测（可用作解释"喂更多上下文不等于更可靠"）。
变更规模与缺陷风险相关：业界大量基于 churn、files changed、改动范围的缺陷预测与风险模型实践（很多组织内部也能从 Git+缺陷单复核这一点）。
分布式系统复杂度来源：一致性、容错、可观测性与发布治理是 L4/L5 的核心（可参考常见分布式系统工程书籍/实践：超时重试、幂等、熔断、SLO 等）。

Claude+ 可落地方案（区分 Claude 现有功能 vs 需手动/工程改造）+ Mermaid 全流程图

1) 能力清单：哪些是 Claude 现有功能，哪些需要你们改造实现

1.1 Claude 现有功能（开箱即用，取决于你使用的入口：Web/IDE/Claude Code/API）

能力	Claude 自带？	你怎么用它	解决什么问题
长文本理解与总结（PRD/设计/日志）	是	把 PRD、设计文档、错误日志喂给 Claude，让它总结、提问、生成任务卡	需求不清、信息分散
结构化输出（按模板生成文档/清单/diff）	是	用固定提示词协议强制输出：计划→设计→diff→测试命令	输出不可控、难审查
多轮迭代对话（基于反馈修正）	是	将 CI 失败日志作为新输入，让它给最小修复 diff	"结果不符合预期"修复效率
代码生成/重构/测试生成	是	仅在"限定文件范围"内生成变更；要求同时生成测试	单点实现速度、减少遗漏
对上传/粘贴内容的上下文引用	是	只提供"上下文包要求的文件"，避免喂全仓库	长上下文退化

说明：Claude 本身不会替你"自动理解整个仓库"，它的稳定性来自你给的上下文是否足够且边界清晰。

1.2 需要你们手动制定流程/产物（不一定写代码，但要落到仓库与团队规范）

项目要素	Claude 自带？	需要你做什么（手动/规范）	目的
分层产品文档体系（Charter/PRD）	否	在 repo 建 `/docs`，定义模板与冻结点；Claude 负责填写/更新草稿，人审核合并	降低"需求不清"与反复沟通
模块责任边界（Module Card）	否	为每模块写"负责/不负责/接口/数据归属/依赖"	避免跨模块乱改、架构漂移
任务卡（Task Card）机制	否	强制任何变更先有任务卡：范围、验收、文件清单、测试策略	把大问题切小、可验证
上下文包（Context Pack）	否	规定每次给 Claude 的输入只来自 CP 列出的文件/契约/日志	对抗过长上下文
小步 PR 与变更范围限制	否	团队约定：单 PR 文件数、跨模块必须拆分	控制回归风险、便于评审
ADR（架构决策记录）	否	重大决策（依赖、分层、协议）写 ADR；Claude 可生成草稿	保证长期一致性

1.3 需要"工程化方案/工具链"实现（可选但对大项目很关键）

能力/工具	Claude 自带？	通常怎么实现	解决什么问题
RepoMap（仓库索引）自动生成/更新	否	脚本扫描目录树+关键入口，生成 `docs/design/repomap.md`	大仓库"找不到相关文件"
代码检索/RAG（只喂相关片段）	否	ripgrep/ctags/LSIF/向量库；按模块/符号检索后拼装上下文	长上下文退化、检索失败
变更影响分析（谁依赖谁）	否	依赖图工具（语言特定），或基于 import/调用关系构建图	减少误改、评估回归面
强制门禁（CI：lint/typecheck/unit/contract/integration）	否	GitHub Actions/GitLab CI；契约测试（OpenAPI/Proto）	把"看起来对"变成"可证明对"
架构守护（依赖规则/禁止跨层/循环依赖）	否	ESLint rules、ArchUnit、dep-cruiser、bazel query 等	防止架构漂移
自动生成/校验契约（OpenAPI/Proto/Schema）	否	contract-first：先写 schema 再生成 stubs；或从代码反推但需校验	分布式/多模块一致性

结论：Claude 提供的是"生成与理解能力"；要把它用于中大型工程，必须用文档/任务/契约/CI/检索把输入输出"工程化"。

2) Claude+ 的落地目录与角色分工（最小可行）

建议最小落地（不引入复杂工具）先建：

复制代码

docs/
  00_charter.md
  prd/
  design/
    architecture.md
    modules/
    api/
    adr/
  tasks/
  context/

角色分工（小团队也能兼任）：

Owner/架构负责人：审核模块边界、ADR、跨模块变更
开发：按 Task/CP 与 Claude 迭代，提交小步 PR
测试/质量（可兼职）：维护验收标准、CI 门禁、回归清单

3) Mermaid：整体优化过程（从"常规用法"到"Claude+工程化"）

3.1 从问题到解决：优化闭环图

需求描述不清
结果不符合预期
改动范围过大
常规使用Claude: 贴需求->出代码
出现问题?
反复对话澄清\n上下文变长
返工/补丁式修复\n架构漂移
跨模块误改\n回归风险
引入PRD/Charter\n冻结需求事实
引入验收标准+测试\n可验证输出
引入模块卡+契约\n锁定边界
任务卡拆分
上下文包CP\n只提供相关文件
小步PR + CI门禁
Claude+工程化稳定迭代

4) Mermaid：项目构建/交付过程（可执行工作流）

4.1 标准交付流水线（每个需求都走一遍）

CI/测试 Repo(文档/代码) Claude 开发(人) 需求方/产品 CI/测试 Repo(文档/代码) Claude 开发(人) 需求方/产品 alt [CI失败] 提交需求/问题描述 1 生成TASK草案(不写代码) 2 TASK-xxxx.md(目标/非目标/验收/范围/问题) 3 提交TASK(评审/冻结) 4 基于TASK生成CP(上下文包) 5 CP-xxxx.md(所需文件<=8/契约片段/禁止区) 6 提供CP要求的文件内容/日志/契约 7 变更计划+设计更新(先契约/模块卡) 8 合并契约/设计(必要时先独立PR) 9 允许在限定文件范围内实现(输出diff+测试) 10 Code diff + tests + 验证命令 11 提交PR(小步) 12 触发lint/typecheck/unit/contract/integration 13 通过/失败日志 14 只给失败日志+相关文件(<=3)\n要求最小修复diff 15 最小修复diff 16 更新PR 17 重新验证 18 通过 19 合并发布 20

5) Mermaid：文档分层与代码模块的对应关系（防止上下文膨胀）

00_charter.md 项目宪法
PRD(按业务域)
Module Cards\n模块责任卡
API/Schema\n契约文件
Task Cards\n任务卡(小步)
Context Pack 上下文包(<=8文件)
代码变更(diff/PR)
CI门禁\n测试/契约/静态检查
合并/发布

6) "可落地"的实施清单：按投入分三档

档位 A（1--3 天能落地，立刻改善）

建 docs/00_charter.md
每次变更必须有 TASK（验收标准+范围+文件清单）
Claude 输出必须为：计划 → diff → 测试命令
约束：单 PR ≤ 10 files（先强行控住）

档位 B（1--2 周，支撑 L2/L3）

modules/* 模块责任卡
repomap.md（人工先写也行）
OpenAPI/Schema 作为契约源（哪怕只覆盖关键接口）
CI：lint/typecheck/unit test

档位 C（2--6 周，支撑更大代码结构/多服务）

代码检索/RAG：按符号与模块拼装上下文
契约测试/集成测试门禁
依赖规则守护（禁止跨层/循环依赖）
ADR 流程固化（架构不变量外化）

Claude+

把"手动制定的流程/产物"和"工程化工具链"与 Claude 集成，关键是让 Claude 在每次工作时都能：自动拿到正确上下文（读到规则与文档）→ 按固定协议产出（可审查的 diff/文档）→ 被 CI/工具链校验与约束（不通过就回退）。下面给出一套可落地的集成方案，从轻量到完整工程化。

1) 集成目标拆解（要集成的不是"模型"，而是"工作流"）

需要集成的两类东西：

A. 手动流程/产物（文档、规范、任务卡）

集成目标：

Claude 能找到：项目宪法、模块边界、契约、任务模板
Claude 会遵守：不越界改、不做大改动、先设计后实现
Claude 的输出能落库：形成可评审的文档与 PR

B. 工程化工具链（可选但关键）

集成目标：

Claude 能利用工具链：检索相关代码、生成/更新契约、跑测试
工具链能约束 Claude：架构规则、契约兼容、测试门禁
失败日志能形成闭环输入：Claude 据此做最小修复

2) 最小集成（不写额外工具也能落地）：仓库规范 + 提示词协议

这是最常见、成本最低的集成方式：用仓库文件做"唯一事实源"，用固定 Prompt 做"执行协议"。

2.1 在仓库放"Claude 运行手册"（单文件即可）

新增：docs/claude/README.md（或 CONTRIBUTING.md 里增加 Claude 段落），内容包括：

本仓库文档层级与优先级（Charter > ADR > Module Card > Contract > Task）
变更流程：必须先 TASK，再 CP，再设计，再实现
输出格式：必须提供文件清单 + diff + 测试命令
变更边界：禁止触碰哪些目录、跨模块需批准
PR 约束：单 PR 文件数上限、不得无关重构

2.2 把模板固化（让 Claude 每次"填空"）

放在：

docs/tasks/_template.md
docs/context/_template.md
docs/design/modules/_template.md
docs/design/adr/_template.md

Claude 的工作就变成"按模板生成/更新"，评审合并即可。

2.3 对话时的固定开场（强制 Claude 读规则）

每次任务开头都要求：

"先读取并总结 docs/claude/README.md 的约束"
"再读取本次 TASK 与涉及模块卡"
"未完成前，不得写代码"

这种做法的缺点：需要人工确保 Claude 真的读了文件；优点：不用开发工具。

3) 标准集成（推荐）：把 Claude 融入 PR 工作流（文档→代码→CI）

这一层开始把"流程/产物"与"工具链门禁"绑在一起，让 Claude 的输出天然进入工程闭环。

3.1 用 PR 模板把流程写死（集成到 Git）

在仓库加 .github/pull_request_template.md（或 GitLab 模板）：

对应 TASK 链接
验收标准勾选
变更范围（文件/模块）
CI 通过截图/链接
回滚方案

要求 Claude 生成 PR 描述时必须按该模板输出，这样审查与协作标准化。

3.2 CI 门禁让"规范可执行"

最低门禁建议：

lint / format
typecheck（如 TS/Go/Java）
unit tests
-（若有 API）schema 校验（OpenAPI/Proto lint）

这样 Claude 即便"写偏了"，也会被 CI 拦下，日志再喂给 Claude 修复。

3.3 失败日志闭环

只需把 CI 输出（原样）喂给 Claude，并加规则：

"只允许修改失败相关文件（≤3）"
"输出最小修复 diff"
"不得重构"

这一步非常有效，能把"结果不符合预期"变成可重复的修复流程。

4) 深度集成（大项目关键）：检索/RAG + 变更影响分析 + 架构守护

这一层是把"工程化工具链"真正接到 Claude 的输入选择上，解决提到的"过长上下文、过大代码结构"。

4.1 RepoMap + 自动上下文拼装（RAG/检索）

做法：

维护 docs/design/repomap.md（目录树 + 关键入口 + 模块职责）
增加脚本 tools/context_pack.py（或任意语言）：
- 输入：TASK（目标、模块、关键符号、路径）
- 输出：CP（文件清单 + 相关片段）
- 片段来源：ripgrep/ast 解析/ctags/lsif/向量检索

Claude 只看到"相关片段"，而不是全仓库，从根上缓解长上下文退化。

集成点：

在 IDE/CLI 运行 make cp TASK=TASK-001 得到 CP
将 CP + 片段直接喂给 Claude（或让工具调用 Claude API）

4.2 变更影响分析（防止跨模块误改）

做法：

静态依赖图工具（语言相关）+ 规则文件（例如允许依赖层级）
在 CI 里运行：如果引入了新循环依赖/跨层依赖，直接失败

集成点：

Claude 在"计划阶段"必须引用依赖图结果：本次变更影响哪些模块
CI 作为硬门禁保证它不越界

4.3 契约测试/兼容性门禁（分布式必备）

做法：

OpenAPI/Proto 为唯一契约源
CI 里做 breaking change 检测（例如 openapi-diff / buf breaking）
服务间契约测试（consumer-driven contract 也行）

集成点：

Claude 先改契约，再改实现
breaking 检测失败 → 作为日志喂回 Claude，要求给出兼容方案（版本化/双写双读等）

5) 集成架构图

5.1 Claude + 文档/规范/工具链的集成闭环

仓库事实源
pass
fail logs
开发者
docs/tasks/TASK-xxx.md
docs/context/CP-xxx.md
00_charter.md
docs/design/adr/*
docs/design/modules/*
docs/design/api/*
docs/claude/README.md
Claude
输出: 文件清单+diff+测试命令
Pull Request
CI门禁: lint/typecheck/unit/contract/integration
合并/发布

6) 集成落地清单（按投入递进）

Level 1（1--2 天）

增加 docs/claude/README.md（规则手册）
增加 TASK/CP 模板
规定 Claude 输出必须 diff + 测试命令
PR 模板绑定 TASK

Level 2（1--2 周）

CI：lint/typecheck/unit
契约文件（OpenAPI/Proto）进入仓库
失败日志闭环流程固化

Level 3（2--6 周，大仓库/多模块）

RepoMap 自动生成或人工维护
context_pack 脚本：检索相关文件/片段拼 CP
依赖图 + 架构规则门禁
breaking change 检测 + 契约测试

7) 关键设计：让 Claude "必须引用事实源"，否则就会漂

无论你用网页端还是 API/IDE，建议制定一条硬规则：

Claude 在输出计划/设计时，必须列出"依据"：
- 引用了哪些仓库文档（Charter/ADR/Module/Contract/TASK/CP）
- 引用了哪些代码文件（路径+关键段落）
未引用依据的回答，视为不合格，不进入实现阶段

这相当于把"继承"从模型记忆变成"显式引用"。