GrowPIP
← 返回所有素材

INFO · info-20251219-082

软件项目持续演进宪章 v2.0（OpenSpec 框架）

[INFO] 软件项目持续演进宪章 v2.0（OpenSpec 框架）

  • 时间: 2024-12-19
  • 类型: 方法论/开发框架
  • 来源: 个人设计
  • 置信度: 9/10
  • 标签: #AI-Coding #规范驱动 #OpenSpec #开发流程 #人机协作

核心理念

Spec 不是文档负担，而是人类控制 AI 产出的唯一杠杆。

时代背景

AI 协作编码面临新挑战：

  • AI 的能力边界由上下文决定
  • 上下文在对话中消散
  • 需求散落在聊天历史，决策背景被遗忘
  • AI 每次对话都从零开始猜测

范式转变

旧范式新范式
人类写代码人类定义行为契约
文档是负担Spec 是指令集
AI 辅助编码AI 从 Spec 生成代码

核心原则

原则定义实践
单一事实来源每个行为规范有且仅有一个权威定义specs/ 是唯一合法依据
变更驱动所有修改始于明确的变更提案禁止未经 changes/ 流程的直接修改
规范即契约Spec 是 AI 必须遵循的指令代码必须与 Spec 一致
知识可溯源每个决策都有背景记录ADR 记录为什么，Spec 记录是什么

人机分工

┌─────────────────────────────────────┐
│            人类职责                 │
│  • 定义 Spec（What + Why）          │
│  • 审核变更提案                     │
│  • 做出架构决策                     │
│  • 验收最终产出                     │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│            AI 职责                  │
│  • 根据 Spec 生成代码（How）        │
│  • 根据 Spec 生成测试               │
│  • 更新派生文档                     │
│  • 发现歧义时暂停并提出             │
└─────────────────────────────────────┘

文档体系架构

project/
├── CLAUDE.md                 # AI 协作总纲（必读）
├── openspec/                 # 规范层 + 过程层
│   ├── project.md            # 项目上下文
│   ├── specs/                # 当前事实来源
│   ├── changes/              # 进行中的变更提案
│   └── archive/              # 已完成变更归档
├── knowledge-base/           # 决策与知识
│   ├── decisions/            # ADR
│   └── domain/glossary.md    # 术语表（必须）
├── requirements/             # 业务需求
└── docs/                     # 派生层：对外文档

文档层级职能

层级目录回答的问题
AI 总纲CLAUDE.mdAI 如何在本项目工作？
规范层specs/系统当前行为是什么？
过程层changes/正在进行什么变更？
决策层decisions/为什么这样设计？
领域层domain/业务概念如何定义？

Spec 格式标准

# <Capability> Specification

## Purpose
<模块职责，1-2 句话>

## Requirements

### Requirement: <需求名称>
<使用 SHALL/MUST/SHOULD/MAY 关键词>

#### Scenario: <场景名称>
- **GIVEN** <前置条件>
- **WHEN** <触发条件>
- **THEN** <预期结果>

关键词语义

关键词语义测试要求
SHALL / MUST强制要求必须有测试
SHOULD推荐行为建议有测试
MAY可选行为如实现则测试

核心工作流

1. PROPOSE  →  2. ALIGN  →  3. IMPLEMENT  →  4. ARCHIVE
   提案          对齐          实现             归档

流程详解

阶段动作
PROPOSE创建 changes/<id>/：proposal.md + tasks.md + specs delta
ALIGN人类审阅 → 协作迭代 → 达成共识
IMPLEMENT按 tasks.md 顺序实现，同时生成测试
ARCHIVEDelta 合并入 specs/，提案移入 archive/

变更分级

级别触发条件流程
Trivialtypo、注释直接 PR
MinorBug 修复简化提案
Standard新功能完整 OpenSpec
Major架构变更OpenSpec + ADR + 评审

AI 禁止行为

  • ❌ 基于对话历史做关键决策——必须查阅 specs/
  • ❌ 直接修改代码而不创建变更提案
  • ❌ 实现与 specs/ 规范冲突的行为
  • ❌ 在 specs/ 有明确定义时自行发挥

歧义处理规则

发现以下问题时，暂停实现并向人类报告：

  • 场景未覆盖的边界条件
  • 需求之间的矛盾
  • 术语定义不明确
  • 缺少错误处理规范

渐进式采纳路径

Level 0: 基础设施
├── 创建目录结构
├── 编写 CLAUDE.md
└── 编写 project.md

Level 1: 新功能试点
├── 选取一个新功能
├── 完整走一遍 OpenSpec 流程
└── 复盘并调整

Level 2: 流程固化
├── 所有新功能必须走 OpenSpec
└── 建立 PR 检查清单

Level 3: 存量消化
├── 修改时逆向工程出 Spec
└── 逐步补充 knowledge-base/

Level 4: 体系化治理
├── 自动化检查全面覆盖
└── 定期审计机制运行

最小可行起步

project/
├── CLAUDE.md                    # 必须
├── openspec/
│   ├── project.md               # 必须
│   ├── specs/<核心模块>/spec.md # 必须
│   └── changes/                 # 必须
└── knowledge-base/domain/glossary.md  # 必须

最小承诺：所有新功能必须先写 Spec，AI 必须先读 Spec。

核心洞察

  1. 编写精确的 Spec 比编写代码更重要——AI 可以从好的 Spec 生成好的代码，反之则不然
  2. Spec 是给 AI 的持久化、版本化、可审查的指令集
  3. 人类的核心职责从"写代码"转向"定义行为契约"

与知识库的关联

与 INFO 的关联

INFO关联点
INFO-074AI时代知识工作者 → 人的选择是 AI 的上限
INFO-066AI 驾驶舱 → Spec 是方向盘
INFO-057AI Coding 三维记忆 → Spec 是 Reference Memory

与 NODE 的关联

NODE关联点
NODE-AI-AgentAgent 的行为边界由 Spec 定义
NODE-科学品味选择"定义什么"需要品味
NODE-知行合一Spec = 知，Code = 行

可提炼的 RULE

  • RULE-先 Spec 后代码：AI 编码前必须有明确 Spec
  • RULE-单一事实来源：每个行为规范只有一个权威定义

关联

  • 相关: INFO-20251219-074（AI时代知识工作者）
  • 相关: INFO-20251219-057（AI Coding 三维记忆系统）
  • 触发规则: RULE-假设验证循环（渐进式采纳）
  • 待验证: 在实际项目中应用效果