Context Driven Development

Context-Driven Development

指导如何将上下文作为与代码并列的管理产物来实现和维护，通过结构化的项目文档实现一致的 AI 交互和团队对齐。

何时不使用此技能

• 任务与上下文驱动开发无关
• 你需要此范围之外的其他领域或工具

指令

• 明确目标、约束和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可操作的步骤和验证方法。
• 如需详细示例，请打开 resources/implementation-playbook.md。

何时使用此技能

• 使用 Conductor 设置新项目
• 理解上下文产物之间的关系
• 在 AI 辅助开发会话之间保持一致性
• 引导团队成员加入现有 Conductor 项目
• 决定何时更新上下文文档
• 管理 greenfield 与 brownfield 项目上下文

核心理念

上下文驱动开发将项目上下文视为与代码并列管理的一等产物。不依赖临时提示或分散的文档，而是建立一个持久的、结构化的基础来指导所有 AI 交互。

关键原则：

1. 上下文先于代码：在实现之前定义你要构建什么以及如何构建
2. 活文档：上下文产物随项目演进
3. 单一真实来源：每类信息有一个权威位置
4. AI 对齐：一致的上下文产生一致的 AI 行为

工作流

遵循 上下文 → 规格与计划 → 实现 工作流：

1. 上下文阶段：建立或验证项目上下文产物存在且是最新的
2. 规格阶段：定义工作单元的需求和验收标准
3. 计划阶段：将规格分解为分阶段的可执行任务
4. 实现阶段：按照既定工作流模式执行任务

产物关系

product.md - 定义做什么和为什么

目的：捕获产品愿景、目标、目标用户和业务背景。

内容：

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

更新时机：

• 产品愿景或目标变化
• 规划新的主要功能
• 目标受众转变
• 业务优先级演进

product-guidelines.md - 定义如何沟通

目的：建立品牌语调、消息标准和沟通模式。

内容：

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

更新时机：

• 品牌指南变化
• 引入新术语
• 沟通模式需要优化

tech-stack.md - 定义用什么

目的：记录技术选型、依赖和架构决策。

内容：

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

更新时机：

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

workflow.md - 定义如何工作

目的：建立开发实践、质量门和团队工作流。

内容：

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

更新时机：

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

tracks.md - 追踪正在发生什么

目的：所有工作单元的注册表，包含状态和元数据。

内容：

• 活跃 tracks 及当前状态
• 已完成 tracks 及完成日期
• Track 元数据（类型、优先级、负责人）
• 指向各个 track 目录的链接

更新时机：

• 创建新 tracks
• Track 状态变化
• Tracks 完成或归档

上下文维护原则

保持产物同步

确保一个产物的变更反映在相关文档中：

• product.md 中的新功能 → 如需新依赖则更新 tech-stack.md
• 完成的 track → 更新 product.md 以反映新能力
• 工作流变更 → 更新所有受影响的 track 计划

添加依赖时更新 tech-stack.md

添加任何新依赖之前：

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

功能完成时更新 product.md

完成功能 track 后：

1. 将功能从"计划中"移至"已实现"在 product.md 中
2. 更新任何受影响的成功指标
3. 记录与原计划的任何范围变更

实现前验证上下文

开始任何 track 之前：

1. 阅读所有上下文产物
2. 标记任何过时信息
3. 在继续之前提出更新建议
4. 与相关方确认上下文准确性

Greenfield 与 Brownfield 处理

Greenfield 项目（新建）

对于新项目：

1. 运行 /conductor:setup 交互式创建所有产物
2. 回答关于产品愿景、技术偏好和工作流的问题
3. 为选择的语言生成初始风格指南
4. 创建空的 tracks 注册表

特点：

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

Brownfield 项目（现有）

对于现有代码库：

1. 运行 /conductor:setup 并启用现有代码库检测
2. 系统分析现有代码、配置和文档
3. 基于发现的模式预填充产物
4. 审查和优化生成的上下文

特点：

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

收益

团队对齐

• 新团队成员通过显式上下文更快上手
• 跨团队一致的术语和约定
• 对产品目标和技术决策的共同理解

AI 一致性

• AI 助手跨会话产生对齐的输出
• 减少每次交互中重新解释上下文的需求
• 基于文档标准的可预测行为

制度记忆

• 决策和理由得以保留
• 上下文在团队变更中存续
• 历史上下文为未来决策提供参考

质量保证

• 标准明确且可验证
• 与上下文的偏差可检测
• 质量门已文档化且可执行

目录结构

conductor/
├── index.md              # 导航中心，链接所有产物
├── product.md            # 产品愿景和目标
├── product-guidelines.md # 沟通标准
├── tech-stack.md         # 技术偏好
├── workflow.md           # 开发实践
├── tracks.md             # 工作单元注册表
├── setup_state.json      # 可恢复的设置状态
├── code_styleguides/     # 特定语言约定
│   ├── python.md
│   ├── typescript.md
│   └── ...
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md

上下文生命周期

1. 创建：通过 /conductor:setup 初始设置
2. 验证：每个 track 前验证
3. 演进：随项目增长更新
4. 同步：保持产物对齐
5. 归档：记录历史决策

上下文验证清单

在开始任何 track 的实现之前，验证上下文：

产品上下文

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

技术上下文

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

工作流上下文

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

Track 上下文

• tracks.md 显示所有活跃工作
• 没有过时或废弃的 tracks
• tracks 之间的依赖已注明

常见反模式

避免这些上下文管理错误：

过时上下文

问题：上下文文档变得过时且误导。 解决方案：作为每个 track 完成流程的一部分更新上下文。

上下文蔓延

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

隐式上下文

问题：依赖未捕获在产物中的知识。 解决方案：如果你反复引用某些内容，将其添加到适当的产物中。

上下文囤积

问题：一人维护上下文而无团队输入。 解决方案：在 pull request 中审查上下文产物；使更新协作化。

过度规格化

问题：上下文变得如此详细以至于无法维护。 解决方案：保持产物专注于影响 AI 行为和团队对齐的决策。

与开发工具集成

IDE 集成

配置 IDE 以突出显示上下文文件：

• 固定 conductor/product.md 以便快速参考
• 将 tech-stack.md 添加到项目笔记
• 从风格指南创建常用模式的代码片段

Git Hooks

考虑 pre-commit hooks：

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

CI/CD 集成

在流水线中包含上下文验证：

• 检查 tech-stack.md 与实际依赖匹配
• 验证上下文文档中的链接可解析
• 确保 tracks.md 状态与 git 分支状态匹配

会话连续性

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

开始新会话

1. 阅读 index.md 定位自己
2. 检查 tracks.md 了解活跃工作
3. 审查相关 track 的 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. 保持可操作：每个上下文项都应指导决策或行为

局限性

• 仅当任务明显符合上述描述的范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。