context-driven-development

上下文驱动开发

指南：将上下文作为与代码并行管理的工件进行实现和维护，通过结构化项目文档，实现一致的 AI 交互和团队协同。

何时使用此技能

• 使用结构化上下文搭建新项目
• 了解各上下文工件之间的关系
• 在 AI 辅助开发过程中保持一致性
• 帮助新团队成员熟悉现有项目
• 判断何时更新上下文文档
• 管理从零开始与已有代码项目的上下文

核心理念

上下文驱动开发将项目上下文视为与代码并行管理的一等工件。不要依赖临时提示词或零散文档，而应建立持久、结构化的基础，为所有 AI 交互提供依据。

核心原则：

1. 上下文先于代码：在实现之前，先定义要构建什么以及如何构建
2. 持续更新的文档：上下文工件随项目不断演进
3. 唯一事实来源：每类信息都有一个权威位置
4. 与 AI 保持一致：一致的上下文带来一致的 AI 行为

工作流

遵循 Context → Spec & Plan → Implement 工作流：

1. 上下文阶段：建立或确认项目上下文工件存在且内容为最新
2. 规格说明阶段：为工作单元定义需求和验收标准
3. 规划阶段：将规格说明拆分为分阶段、可执行的任务
4. 实现阶段：按照既定的工作流模式执行任务

工件之间的关系

product.md - 定义内容和原因

用途：记录产品愿景、目标、目标用户和业务背景。

内容：

• 产品名称和一句话简介
• 问题陈述和解决方案
• 目标用户画像
• 核心功能和能力
• 成功指标和 KPI
• 产品路线图（高层级）

更新时机：

• 产品愿景或目标发生变化
• 计划推出新的主要功能
• 目标受众发生变化
• 业务优先级发生变化

product-guidelines.md - 定义沟通方式

用途：确立品牌声音、消息传达标准和沟通模式。

内容：

• 品牌声音和语调指南
• 术语和词汇表
• 错误消息规范
• 面向用户的文案标准
• 文档风格

更新时机：

• 品牌指南发生变化
• 引入新术语
• 需要完善沟通模式

tech-stack.md - 定义所用技术

用途：记录技术选型、依赖项和架构决策。

内容：

• 主要语言和框架
• 带版本号的关键依赖项
• 基础设施和部署目标
• 开发工具和环境
• 测试框架
• 代码质量工具

更新时机：

• 添加新依赖项
• 升级主要版本
• 更改基础设施
• 采用新工具或模式

workflow.md - 定义工作方式

用途：确立开发实践、质量门禁和团队工作流。

内容：

• 开发方法（TDD 等）
• Git 工作流和提交规范
• 代码评审要求
• 测试要求和覆盖率目标
• 质量保证门禁
• 部署流程

更新时机：

• 团队实践不断演进
• 质量标准发生变化
• 采用新的工作流模式

tracks.md - 跟踪当前进展

用途：记录所有工作单元及其状态和元数据。

内容：

• 处于活动状态的工作流及其当前状态
• 已完成的工作流及完成日期
• 工作流元数据（类型、优先级、负责人）
• 指向各工作流目录的链接

更新时机：

• 创建新工作流
• 工作流状态发生变化
• 工作流已完成或归档

上下文维护原则

保持工件同步

确保某个工件中的更改反映在相关文档中：

• 在 product.md 中新增功能 → 如果需要新增依赖项，则更新 tech-stack.md
• 完成某个轨道 → 更新 product.md 以反映新功能
• 更改工作流 → 更新所有受影响的轨道计划

新增依赖项时更新 tech-stack.md

新增任何依赖项之前：

1. 检查现有依赖项是否能满足需求
2. 说明新增依赖项的理由
3. 添加版本约束
4. 注明任何配置要求

功能完成时更新 product.md

完成某个功能轨道后：

1. 在 product.md 中将功能从“计划中”移至“已实现”
2. 更新所有受影响的成功指标
3. 记录相较于原计划的范围变更

实施前验证上下文

开始任何轨道之前：

1. 阅读所有上下文工件
2. 标记所有过时信息
3. 提出更新建议后再继续
4. 与利益相关者确认上下文准确无误

新项目与现有项目的处理方式

新项目

对于新项目：

1. 通过交互方式创建所有工件
2. 回答有关产品愿景、技术偏好和工作流的问题
3. 为所选语言生成初始风格指南
4. 创建空的轨道注册表

特点：

• 完全掌控上下文结构
• 在代码出现之前定义标准
• 尽早建立模式

现有项目

对于现有代码库：

1. 分析现有代码、配置和文档
2. 根据发现的模式预先填充工件
3. 审查并完善生成的上下文
4. 协调现有模式与期望模式

特点：

• 从现有代码中提取隐含上下文
• 协调现有模式与期望模式
• 记录技术债务和现代化计划
• 在建立标准的同时保留有效模式

优势

团队协作一致

• 新团队成员借助明确的上下文更快上手
• 团队使用统一的术语和约定
• 对产品目标和技术决策形成共同理解

AI 输出一致

• AI 助手在不同会话中生成一致的输出
• 减少在每次交互中重复解释上下文的需要
• 基于已记录的标准实现可预测的行为

组织记忆

• 保留决策及其理由
• 团队变动不会导致上下文丢失
• 历史上下文为未来决策提供参考

质量保障

• 标准明确且可验证
• 可以发现偏离上下文的情况
• 质量门禁有据可查且可执行

目录结构

.claude/context/
├── product.md            # Product vision and goals
├── product-guidelines.md # Communication standards
├── tech-stack.md         # Technology preferences
├── workflow.md           # Development practices
├── tracks.md             # Work unit registry
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md

上下文生命周期

1. 创建：初始设置
2. 验证：在每个轨道开始前进行验证
3. 演进：随着项目发展而更新
4. 同步：保持工件一致
5. 归档：记录历史决策

上下文验证清单

开始实施任何轨道之前，请验证上下文：

产品上下文

• product.md 反映当前产品愿景
• 目标用户描述准确
• 功能列表为最新版本
• 已定义成功指标

技术上下文

• tech-stack.md 列出所有当前依赖项
• 版本号准确
• 基础设施目标正确
• 已记录开发工具

工作流上下文

• workflow.md 描述当前实践
• 已定义质量门禁
• 已指定覆盖率目标
• 已记录提交约定

轨道上下文

• tracks.md 显示所有进行中的工作
• 没有过时或已放弃的轨道
• 已注明轨道之间的依赖关系

常见反模式

避免以下上下文管理错误：

上下文过时

问题：上下文文档变得过时并产生误导。 解决方案：将更新上下文纳入每个轨道的完成流程。

上下文泛滥

问题：信息分散在多个位置。 解决方案：使用已定义的产物结构；避免创建新的文档类型。

隐式上下文

问题：依赖未记录在产物中的知识。 解决方案：如果某项内容会被反复引用，就将其添加到相应的产物中。

上下文囤积

问题：由一个人维护上下文，缺少团队参与。 解决方案：在拉取请求中审查上下文产物；协作更新。

过度细化

问题：上下文过于详细，难以维护。 解决方案：让产物聚焦于影响 AI 行为和团队共识的决策。

与开发工具集成

IDE 集成

配置 IDE，让上下文文件醒目易见：

• 固定 product.md，方便快速查阅
• 将 tech-stack.md 添加到项目备注
• 根据样式指南为常见模式创建代码片段

Git 钩子

考虑使用提交前钩子，以便：

• 在依赖项发生变化但未更新 tech-stack.md 时发出警告
• 在功能分支合并时提醒更新 product.md
• 验证上下文产物的语法

CI/CD 集成

在流水线中加入上下文验证：

• 检查 tech-stack.md 是否与实际依赖项一致
• 验证上下文文档中的链接是否有效
• 确保 tracks.md 中的状态与 git 分支状态一致

会话连续性

通过持久化上下文支持跨会话开发：

开始新会话

1. 阅读 product.md，了解项目概况
2. 查看 tracks.md 中的进行中工作
3. 阅读相关轨道的 plan.md，了解当前任务
4. 确认上下文产物是最新的

结束会话

1. 在 plan.md 中更新当前进度
2. 记录所有阻碍因素或已作出的决策
3. 提交进行中的工作，并注明清晰的状态
4. 如果状态发生变化，更新 tracks.md

处理中断

如果任务进行中被打断：

1. 将任务标记为 [~]，并注明停止位置
2. 将未完成的工作提交到功能分支
3. 在 plan.md 中记录所有尚未提交的决策

最佳实践

1. 先阅读上下文：开始工作前，始终阅读相关产物
2. 小步更新：逐步更改上下文，不要大规模重写
3. 关联决策：作出实现选择时，引用相关上下文
4. 对上下文进行版本管理：将上下文更改与代码更改一同提交
5. 审查上下文：在代码审查中纳入上下文产物审查
6. 定期验证：开始重大工作前，运行上下文验证清单
7. 沟通变更：上下文产物发生重大变化时通知团队
8. 保留历史记录：使用 git 跟踪上下文随时间的演变
9. 检查过时内容：如果上下文看起来有误，就进行调查并更新
10. 确保可执行：每条上下文信息都应为决策或行为提供依据

铁律

1. 务必在开始任何实现轨道前阅读所有相关上下文产物（product.md、tech-stack.md、workflow.md）——切勿基于过时或未经核实的上下文开始编码。
2. 切勿在已定义的目录结构中存在适用类别时，创建新的产物类型或文档位置——避免上下文泛滥。
3. 务必在同一次提交中将上下文产物与代码更改一并原子更新——在不同拉取请求中单独更新上下文会造成偏差和过时引用。
4. 切勿让任何上下文文件超过 20KB，除非进行轮换或归档——无节制增长会使上下文无法使用，并拖慢 AI 交互。
5. 务必在实现前标记过时或相互矛盾的上下文——过时的 tech-stack.md 或错误的 product.md 属于技术债务，会随着每次 AI 交互不断累积。

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假设任务会被打断：如果没有记录在记忆中，就等于没发生。