Back to Details

context-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Context-Driven Development

上下文驱动开发

Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation.
本指南介绍如何将上下文作为与代码一同管理的工件来实施和维护，通过结构化的项目文档实现一致的AI交互和团队对齐。

When to Use This Skill

什么时候使用此技能

  • Setting up new projects with Conductor
  • Understanding the relationship between context artifacts
  • Maintaining consistency across AI-assisted development sessions
  • Onboarding team members to an existing Conductor project
  • Deciding when to update context documents
  • Managing greenfield vs brownfield project contexts
  • 使用Conductor搭建新项目时
  • 理解上下文工件之间的关系时
  • 在AI辅助开发会话中保持一致性时
  • 向现有Conductor项目的团队成员进行入职培训时
  • 决定何时更新上下文文档时
  • 管理全新项目（Greenfield）与已有项目（Brownfield）的上下文时

Core Philosophy

核心理念

Context-Driven Development treats project context as a first-class artifact managed alongside code. Instead of relying on ad-hoc prompts or scattered documentation, establish a persistent, structured foundation that informs all AI interactions.
Key principles:
  1. Context precedes code: Define what you're building and how before implementation
  2. Living documentation: Context artifacts evolve with the project
  3. Single source of truth: One canonical location for each type of information
  4. AI alignment: Consistent context produces consistent AI behavior
上下文驱动开发将项目上下文视为与代码同等重要的管理工件。无需依赖临时提示或分散的文档，而是建立一个持久、结构化的基础，为所有AI交互提供信息。
关键原则：
  1. 上下文优先于代码：在实施前先定义要构建的内容和方式
  2. 活文档：上下文工件随项目一同演进
  3. 单一事实来源：每种类型的信息都有一个标准存储位置
  4. AI对齐：一致的上下文产生一致的AI行为

The Workflow

工作流程

Follow the Context → Spec & Plan → Implement workflow:
  1. Context Phase: Establish or verify project context artifacts exist and are current
  2. Specification Phase: Define requirements and acceptance criteria for work units
  3. Planning Phase: Break specifications into phased, actionable tasks
  4. Implementation Phase: Execute tasks following established workflow patterns
遵循上下文 → 规格与规划 → 实施的工作流程：
  1. 上下文阶段：确认或验证项目上下文工件已存在且内容最新
  2. 规格阶段：定义工作单元的需求和验收标准
  3. 规划阶段：将规格拆解为分阶段的可执行任务
  4. 实施阶段：遵循既定的工作流模式执行任务

Artifact Relationships

工件关系

product.md - Defines WHAT and WHY

product.md - 定义要做什么（WHAT）和为什么做（WHY）

Purpose: Captures product vision, goals, target users, and business context.
Contents:
  • Product name and one-line description
  • Problem statement and solution approach
  • Target user personas
  • Core features and capabilities
  • Success metrics and KPIs
  • Product roadmap (high-level)
Update when:
  • Product vision or goals change
  • New major features are planned
  • Target audience shifts
  • Business priorities evolve
用途：记录产品愿景、目标、目标用户和业务上下文。
内容：
  • 产品名称和一句话描述
  • 问题陈述和解决方案思路
  • 目标用户画像
  • 核心功能与能力
  • 成功指标和KPI
  • 产品路线图（高阶）
更新时机：
  • 产品愿景或目标发生变化时
  • 计划新增重大功能时
  • 目标受众发生转移时
  • 业务优先级调整时

product-guidelines.md - Defines HOW to Communicate

product-guidelines.md - 定义沟通方式（HOW）

Purpose: Establishes brand voice, messaging standards, and communication patterns.
Contents:
  • Brand voice and tone guidelines
  • Terminology and glossary
  • Error message conventions
  • User-facing copy standards
  • Documentation style
Update when:
  • Brand guidelines change
  • New terminology is introduced
  • Communication patterns need refinement
用途：建立品牌语气、消息传递标准和沟通模式。
内容：
  • 品牌语气和语调指南
  • 术语表和词汇表
  • 错误消息规范
  • 用户面向的文案标准
  • 文档风格
更新时机：
  • 品牌指南发生变化时
  • 引入新术语时
  • 沟通模式需要优化时

tech-stack.md - Defines WITH WHAT

tech-stack.md - 定义用什么工具（WITH WHAT）

Purpose: Documents technology choices, dependencies, and architectural decisions.
Contents:
  • Primary languages and frameworks
  • Key dependencies with versions
  • Infrastructure and deployment targets
  • Development tools and environment
  • Testing frameworks
  • Code quality tools
Update when:
  • Adding new dependencies
  • Upgrading major versions
  • Changing infrastructure
  • Adopting new tools or patterns
用途：记录技术选型、依赖项和架构决策。
内容：
  • 主要语言和框架
  • 带版本号的关键依赖项
  • 基础设施和部署目标
  • 开发工具与环境
  • 测试框架
  • 代码质量工具
更新时机：
  • 添加新依赖项时
  • 升级主要版本时
  • 变更基础设施时
  • 采用新工具或模式时

workflow.md - Defines HOW to Work

workflow.md - 定义工作方式（HOW to Work）

Purpose: Establishes development practices, quality gates, and team workflows.
Contents:
  • Development methodology (TDD, etc.)
  • Git workflow and commit conventions
  • Code review requirements
  • Testing requirements and coverage targets
  • Quality assurance gates
  • Deployment procedures
Update when:
  • Team practices evolve
  • Quality standards change
  • New workflow patterns are adopted
用途：建立开发实践、质量关卡和团队工作流。
内容：
  • 开发方法论（如TDD）
  • Git工作流和提交规范
  • 代码评审要求
  • 测试要求和覆盖率目标
  • 质量保证关卡
  • 部署流程
更新时机：
  • 团队实践演进时
  • 质量标准变化时
  • 采用新工作流模式时

tracks.md - Tracks WHAT'S HAPPENING

tracks.md - 跟踪项目进展（WHAT'S HAPPENING）

Purpose: Registry of all work units with status and metadata.
Contents:
  • Active tracks with current status
  • Completed tracks with completion dates
  • Track metadata (type, priority, assignee)
  • Links to individual track directories
Update when:
  • New tracks are created
  • Track status changes
  • Tracks are completed or archived
用途：所有工作单元的注册表，包含状态和元数据。
内容：
  • 活跃工作单元及其当前状态
  • 已完成工作单元及其完成日期
  • 工作单元元数据（类型、优先级、负责人）
  • 指向单个工作单元目录的链接
更新时机：
  • 创建新工作单元时
  • 工作单元状态变化时
  • 工作单元完成或归档时

Context Maintenance Principles

上下文维护原则

Keep Artifacts Synchronized

保持工件同步

Ensure changes in one artifact reflect in related documents:
  • New feature in product.md → Update tech-stack.md if new dependencies needed
  • Completed track → Update product.md to reflect new capabilities
  • Workflow change → Update all affected track plans
确保一个工件的变更反映在相关文档中：
  • product.md中新增功能 → 若需要新依赖项则更新tech-stack.md
  • 工作单元完成 → 更新product.md以反映新功能
  • 工作流变更 → 更新所有受影响的工作单元计划

Update tech-stack.md When Adding Dependencies

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

Before adding any new dependency:
  1. Check if existing dependencies solve the need
  2. Document the rationale for new dependencies
  3. Add version constraints
  4. Note any configuration requirements
添加任何新依赖项前：
  1. 检查现有依赖项是否能满足需求
  2. 记录新增依赖项的理由
  3. 添加版本约束
  4. 注明任何配置要求

Update product.md When Features Complete

功能完成时更新product.md

After completing a feature track:
  1. Move feature from "planned" to "implemented" in product.md
  2. Update any affected success metrics
  3. Document any scope changes from original plan
完成功能工作单元后：
  1. 将product.md中的功能从“计划中”移至“已实现”
  2. 更新受影响的成功指标
  3. 记录与原始计划的任何范围变更

Verify Context Before Implementation

实施前验证上下文

Before starting any track:
  1. Read all context artifacts
  2. Flag any outdated information
  3. Propose updates before proceeding
  4. Confirm context accuracy with stakeholders
开始任何工作单元前：
  1. 阅读所有上下文工件
  2. 标记任何过时信息
  3. 先提出更新建议再继续
  4. 与利益相关者确认上下文的准确性

Greenfield vs Brownfield Handling

全新项目与已有项目的处理方式

Greenfield Projects (New)

全新项目（Greenfield）

For new projects:
  1. Run 
    /conductor:setup
    to create all artifacts interactively
  2. Answer questions about product vision, tech preferences, and workflow
  3. Generate initial style guides for chosen languages
  4. Create empty tracks registry
Characteristics:
  • Full control over context structure
  • Define standards before code exists
  • Establish patterns early
针对新项目：
  1. 运行
    /conductor:setup
    交互式创建所有工件
  2. 回答关于产品愿景、技术偏好和工作流的问题
  3. 为所选语言生成初始风格指南
  4. 创建空的工作单元注册表
特点：
  • 完全控制上下文结构
  • 在代码编写前定义标准
  • 尽早建立模式

Brownfield Projects (Existing)

已有项目（Brownfield）

For existing codebases:
  1. Run 
    /conductor:setup
    with existing codebase detection
  2. System analyzes existing code, configs, and documentation
  3. Pre-populate artifacts based on discovered patterns
  4. Review and refine generated context
Characteristics:
  • Extract implicit context from existing code
  • Reconcile existing patterns with desired patterns
  • Document technical debt and modernization plans
  • Preserve working patterns while establishing standards
针对现有代码库：
  1. 运行
    /conductor:setup
    并启用现有代码库检测
  2. 系统分析现有代码、配置和文档
  3. 基于发现的模式预填充工件
  4. 审核并优化生成的上下文
特点：
  • 从现有代码中提取隐式上下文
  • 协调现有模式与期望模式
  • 记录技术债务和现代化计划
  • 在建立标准的同时保留现有可用模式

Benefits

优势

Team Alignment

团队对齐

  • New team members onboard faster with explicit context
  • Consistent terminology and conventions across the team
  • Shared understanding of product goals and technical decisions
  • 新团队成员可通过明确的上下文更快完成入职
  • 团队使用一致的术语和规范
  • 对产品目标和技术决策有共同理解

AI Consistency

AI一致性

  • AI assistants produce aligned outputs across sessions
  • Reduced need to re-explain context in each interaction
  • Predictable behavior based on documented standards
  • AI助手在不同会话中生成对齐的输出
  • 无需在每次交互中重复解释上下文
  • 基于文档化标准实现可预测的行为

Institutional Memory

机构记忆

  • Decisions and rationale are preserved
  • Context survives team changes
  • Historical context informs future decisions
  • 决策和理由被保留
  • 上下文不会随团队人员变动而丢失
  • 历史上下文为未来决策提供参考

Quality Assurance

质量保证

  • Standards are explicit and verifiable
  • Deviations from context are detectable
  • Quality gates are documented and enforceable
  • 标准明确且可验证
  • 可检测与上下文的偏差
  • 质量关卡被文档化且可执行

Directory Structure

目录结构

conductor/
├── index.md              # Navigation hub linking all artifacts
├── 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
├── setup_state.json      # Resumable setup state
├── code_styleguides/     # Language-specific conventions
│   ├── python.md
│   ├── typescript.md
│   └── ...
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md
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

Context Lifecycle

上下文生命周期

  1. Creation: Initial setup via 
    /conductor:setup
  2. Validation: Verify before each track
  3. Evolution: Update as project grows
  4. Synchronization: Keep artifacts aligned
  5. Archival: Document historical decisions
  1. 创建：通过
    /conductor:setup
    完成初始设置
  2. 验证：每个工作单元开始前进行验证
  3. 演进：随项目增长而更新
  4. 同步：保持工件之间的对齐
  5. 归档：记录历史决策

Context Validation Checklist

上下文验证清单

Before starting implementation on any track, validate context:
开始任何工作单元的实施前，验证以下上下文：

Product Context

产品上下文

  • product.md reflects current product vision
  • Target users are accurately described
  • Feature list is up to date
  • Success metrics are defined
  • product.md反映当前产品愿景
  • 目标用户描述准确
  • 功能列表是最新的
  • 已定义成功指标

Technical Context

技术上下文

  • tech-stack.md lists all current dependencies
  • Version numbers are accurate
  • Infrastructure targets are correct
  • Development tools are documented
  • tech-stack.md列出所有当前依赖项
  • 版本号准确
  • 基础设施目标正确
  • 开发工具已记录

Workflow Context

工作流上下文

  • workflow.md describes current practices
  • Quality gates are defined
  • Coverage targets are specified
  • Commit conventions are documented
  • workflow.md描述当前实践
  • 已定义质量关卡
  • 指定了覆盖率目标
  • 已记录提交规范

Track Context

工作单元上下文

  • tracks.md shows all active work
  • No stale or abandoned tracks
  • Dependencies between tracks are noted
  • tracks.md显示所有活跃工作
  • 没有过时或已废弃的工作单元
  • 已注明工作单元之间的依赖关系

Common Anti-Patterns

常见反模式

Avoid these context management mistakes:
避免以下上下文管理错误：

Stale Context

过时上下文

Problem: Context documents become outdated and misleading. Solution: Update context as part of each track's completion process.
问题：上下文文档变得过时且具有误导性。 解决方案：将更新上下文作为每个工作单元完成流程的一部分。

Context Sprawl

上下文分散

Problem: Information scattered across multiple locations. Solution: Use the defined artifact structure; resist creating new document types.
问题：信息分散在多个位置。 解决方案：使用定义好的工件结构；避免创建新的文档类型。

Implicit Context

隐式上下文

Problem: Relying on knowledge not captured in artifacts. Solution: If you reference something repeatedly, add it to the appropriate artifact.
问题：依赖未在工件中记录的知识。 解决方案：如果你反复引用某内容，将其添加到相应的工件中。

Context Hoarding

上下文垄断

Problem: One person maintains context without team input. Solution: Review context artifacts in pull requests; make updates collaborative.
问题：仅由一个人维护上下文，无团队参与。 解决方案：在拉取请求中审核上下文工件；让更新过程协作化。

Over-Specification

过度规格化

Problem: Context becomes so detailed it's impossible to maintain. Solution: Keep artifacts focused on decisions that affect AI behavior and team alignment.
问题：上下文过于详细，难以维护。 解决方案：让工件专注于影响AI行为和团队对齐的决策。

Integration with Development Tools

与开发工具的集成

IDE Integration

IDE集成

Configure your IDE to display context files prominently:
  • Pin conductor/product.md for quick reference
  • Add tech-stack.md to project notes
  • Create snippets for common patterns from style guides
配置IDE以突出显示上下文文件：
  • 固定conductor/product.md以便快速参考
  • 将tech-stack.md添加到项目笔记中
  • 根据风格指南创建常用模式的代码片段

Git Hooks

Git钩子

Consider pre-commit hooks that:
  • Warn when dependencies change without tech-stack.md update
  • Remind to update product.md when feature branches merge
  • Validate context artifact syntax
考虑使用以下提交前钩子：
  • 当依赖项变更但未更新tech-stack.md时发出警告
  • 当功能分支合并时提醒更新product.md
  • 验证上下文工件的语法

CI/CD Integration

CI/CD集成

Include context validation in pipelines:
  • Check tech-stack.md matches actual dependencies
  • Verify links in context documents resolve
  • Ensure tracks.md status matches git branch state
在流水线中加入上下文验证：
  • 检查tech-stack.md是否与实际依赖项匹配
  • 验证上下文文档中的链接是否可解析
  • 确保tracks.md的状态与Git分支状态匹配

Session Continuity

会话连续性

Conductor supports multi-session development through context persistence:
Conductor通过上下文持久化支持多会话开发：

Starting a New Session

开始新会话

  1. Read index.md to orient yourself
  2. Check tracks.md for active work
  3. Review relevant track's plan.md for current task
  4. Verify context artifacts are current
  1. 阅读index.md以熟悉情况
  2. 检查tracks.md中的活跃工作
  3. 查看相关工作单元的plan.md了解当前任务
  4. 验证上下文工件是最新的

Ending a Session

结束会话

  1. Update plan.md with current progress
  2. Note any blockers or decisions made
  3. Commit in-progress work with clear status
  4. Update tracks.md if status changed
  1. 更新plan.md记录当前进度
  2. 记录任何障碍或已做出的决策
  3. 提交带有明确状态的进行中工作
  4. 如果状态变更，更新tracks.md

Handling Interruptions

处理中断

If interrupted mid-task:
  1. Mark task as 
    [~]
    with note about stopping point
  2. Commit work-in-progress to feature branch
  3. Document any uncommitted decisions in plan.md
如果任务中途被打断：
  1. 将任务标记为
    [~]
    并注明停止点
  2. 将进行中的工作提交到功能分支
  3. 在plan.md中记录任何未提交的决策

Best Practices

最佳实践

  1. Read context first: Always read relevant artifacts before starting work
  2. Small updates: Make incremental context changes, not massive rewrites
  3. Link decisions: Reference context when making implementation choices
  4. Version context: Commit context changes alongside code changes
  5. Review context: Include context artifact reviews in code reviews
  6. Validate regularly: Run context validation checklist before major work
  7. Communicate changes: Notify team when context artifacts change significantly
  8. Preserve history: Use git to track context evolution over time
  9. Question staleness: If context feels wrong, investigate and update
  10. Keep it actionable: Every context item should inform a decision or behavior
  1. 先读上下文：开始工作前务必阅读相关工件
  2. 小步更新：对上下文进行增量变更，而非大规模重写
  3. 关联决策：做出实施选择时引用上下文
  4. 版本化上下文：将上下文变更与代码变更一同提交
  5. 审核上下文：在代码评审中包含上下文工件的审核
  6. 定期验证：在重大工作开始前运行上下文验证清单
  7. 沟通变更：当上下文工件发生重大变更时通知团队
  8. 保留历史：使用Git跟踪上下文随时间的演进
  9. 质疑过时性：如果上下文感觉有误，调查并更新
  10. 保持可行动性：每个上下文项都应能指导决策或行为