Skip to content

Commit 000be1e

Browse files
zhanglukaclaude
zhangluka
and
claude
committed
docs: add OpenSpec changelog and enhance tools documentation
- Add changelog.md with OpenSpec-style change management - Update index.md to link to the new changelog - Enhance openspec.md with core commands, change management workflow Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 1b21789 commit 000be1e

3 files changed

Lines changed: 202 additions & 4 deletions

File tree

‎tools/changelog.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# phSpec 变更记录
2+
3+
phSpec 项目的变更记录，采用 OpenSpec 风格的变更管理。
4+
5+
## 最近变更
6+
7+
### 2026-04-21 - 添加 review-commands 技能
8+
9+
**变更类型**: 新增功能
10+
11+
**变更 ID**: `add-review-commands`
12+
13+
**状态**: ✅ 已完成
14+
15+
**描述**: 为 phSpec 项目添加各环节制品检查的审查技能，包括规格审查、代码审查和设计审查。
16+
17+
**新增能力**:
18+
- `/phsx:review-spec` - 规格质量审查，检查完整性、清晰度、可实施性
19+
- `/phsx:review-code` - 代码规范合规性审查，验证代码与规格一致性
20+
- `/phsx:review-design` - 设计一致性审查，检查设计与规格关联性
21+
- 增强 `/phsx:verify` 命令，提升检查深度
22+
23+
**技术决策**:
24+
- 使用现有模板生成系统保持架构一致性
25+
- 审查命令作为核心命令，生成到所有 AI 工具
26+
- 参考成熟的 cc-spex 实现逻辑
27+
- 采用建议式审查而非强制门控
28+
- 严格使用 Node.js path 模块确保跨平台兼容
29+
30+
**影响范围**:
31+
- 模板系统: `src/core/templates/skill-templates.ts`
32+
- 工具检测: `src/core/shared/tool-detection.ts`
33+
- 命令生成: `src/core/command-generation/generator.ts`
34+
- 适配器: `src/core/command-generation/adapters/`
35+
36+
**任务完成情况**:
37+
- ✅ 核心命令基础设施 (5/5)
38+
- ✅ Review Spec 命令实现 (9/9)
39+
- ✅ Review Code 命令实现 (13/13)
40+
- ✅ Review Design 命令实现 (13/13)
41+
- ✅ 增强 Verify 命令 (8/8)
42+
- ✅ 报告格式标准化 (4/4)
43+
- ✅ 跨平台兼容性 (4/4)
44+
- ✅ 文档更新 (5/5)
45+
- ✅ 集成测试 (6/6)
46+
- ✅ 手动验证 (7/7)
47+
48+
**详细文档**: 参见 `changes/add-review-commands/` 目录
49+
50+
---
51+
52+
## 变更记录格式
53+
54+
每个变更记录包含以下部分：
55+
56+
### 变更摘要
57+
- **变更类型**: 新增功能 / 功能增强 / 修复 / 重构 / 文档
58+
- **变更 ID**: 变更的唯一标识符
59+
- **状态**: 计划中 / 进行中 / 已完成 / 已回滚
60+
- **描述**: 一句话描述变更内容
61+
62+
### 详细信息
63+
- **新增能力**: 新增或修改的能力列表
64+
- **技术决策**: 关键技术决策及其理由
65+
- **影响范围**: 受影响的代码、文档、配置等
66+
- **任务完成情况**: 任务清单及完成状态
67+
68+
### 变更优先级
69+
- **P0**: 必须立即处理
70+
- **P1**: 验证后处理
71+
- **P2**: 长期规划
72+
73+
## 变更目录结构
74+
75+
```
76+
changes/
77+
├── add-review-commands/
78+
│ ├── .openspec.yaml # OpenSpec 配置
79+
│ ├── design.md # 设计文档
80+
│ ├── proposal.md # 提案文档
81+
│ ├── tasks.md # 任务清单
82+
│ └── specs/ # 规格文档
83+
│ ├── review-spec/
84+
│ ├── review-code/
85+
│ ├── review-design/
86+
│ └── verify/
87+
└── [other-changes]/
88+
```
89+
90+
## 提交变更
91+
92+
新增变更时，请遵循以下步骤：
93+
94+
1. 在 `changes/` 创建新目录，命名格式：`<change-id>`
95+
2. 创建必需的文档文件：
96+
- `.openspec.yaml` - 变更配置
97+
- `proposal.md` - 变更提案
98+
- `design.md` - 设计文档
99+
- `tasks.md` - 任务清单
100+
3. 创建 `specs/` 目录，存放各制品的规格文档
101+
4. 更新本文件，添加变更记录
102+
103+
## 相关文档
104+
105+
- [OpenSpec 官方文档](https://github.com/Fission-AI/OpenSpec)
106+
- [OpenSpec 工具文档](./openspec.md)

‎tools/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,13 @@ Harness 体系完整构建方案，涵盖六大组件设计：
2222
- 定位：Spec-driven development for AI coding assistants
2323
- 特点：无需 API Key、支持 Brownfield 开发、轻量级工作流
2424

25+
### [Change Log](./changelog.md)
26+
27+
项目变更记录，采用 OpenSpec 风格的变更管理。
28+
29+
- 记录所有变更的历史和状态
30+
- 包含变更的提案、设计和任务清单
31+
2532
### [Ralph Loop](./ralph-loop.md)
2633

2734
结合内化 PhSpec 的 Ralph 自动化执行工具。

‎tools/openspec.md‎

Lines changed: 89 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,91 @@ Spec-driven development for AI coding assistants
88

99
## 源码
1010

11-
`/Users/bobby/Projects/Github/zhangluka/OpenSpec/openspec_cs`
11+
- **内化版本**: `/Users/bobby/Projects/Github/zhangluka/OpenSpec/openspec_cs`
12+
- **开源项目**: https://github.com/Fission-AI/OpenSpec
1213

13-
## 特点
14+
## 核心特点
1415

1516
- **无需 API Key**：本地运行，无外部依赖
1617
- **支持 Brownfield（棕地）开发**：可适应现有代码库
1718
- **轻量级工作流**：简洁高效的开发流程
19+
- **跨平台支持**：macOS、Linux、Windows
20+
- **灵活而非僵化**：不强制固定工作流
21+
22+
## 核心命令
23+
24+
| 命令 | 功能 | 说明 |
25+
|------|------|------|
26+
| `/phsx:verify` | 基础验证 | 检查规格与实现的一致性 |
27+
| `/phsx:review-spec` | 规格审查 | 检查规格的完整性、清晰度、可实施性 |
28+
| `/phsx:review-code` | 代码审查 | 验证代码实现与规格的一致性 |
29+
| `/phsx:review-design` | 设计审查 | 检查设计方案与规格的关联性 |
30+
31+
## 变更管理
32+
33+
OpenSpec 采用结构化的变更管理流程，每个变更包含完整的文档：
34+
35+
```
36+
changes/
37+
├── <change-id>/
38+
│ ├── .openspec.yaml # 变更配置
39+
│ ├── proposal.md # 变更提案
40+
│ ├── design.md # 设计文档
41+
│ ├── tasks.md # 任务清单
42+
│ └── specs/ # 规格文档
43+
│ ├── <artifact-1>/
44+
│ ├── <artifact-2>/
45+
│ └── ...
46+
```
47+
48+
### 变更文档说明
49+
50+
**`.openspec.yaml`**
51+
- 变更元数据和配置
52+
- 变更名称、描述、类型等
53+
54+
**`proposal.md`**
55+
- 变更提案文档
56+
- 包含：Why、What Changes、Capabilities、Impact、技术决策
57+
58+
**`design.md`**
59+
- 详细设计文档
60+
- 包含：Context、Goals/Non-Goals、Decisions、Risks/Trade-offs、Migration Plan
61+
62+
**`tasks.md`**
63+
- 任务清单和实现跟踪
64+
- 按功能模块分组
65+
- 使用 checkbox 标记完成状态
66+
67+
**`specs/`**
68+
- 各制品的规格文档
69+
- 每个制品一个目录
70+
- 使用 Spec-Kit 格式
1871

1972
## 快速开始
2073

2174
### 基本工作流
2275

2376
1. 创建 OpenSpec 变更
77+
```bash
78+
cd openspec_cs
79+
openspec new <change-id>
80+
```
81+
2482
2. 编写规范文档
83+
- `proposal.md` - 描述变更提案
84+
- `design.md` - 详细设计
85+
- `specs/` - 各制品规格
86+
2587
3. 执行自动生成
88+
```bash
89+
openspec generate
90+
```
91+
2692
4. 验证输出
93+
```bash
94+
openspec verify
95+
```
2796

2897
### 集成到项目
2998

@@ -35,6 +104,22 @@ cd /Users/bobby/Projects/Github/zhangluka/OpenSpec/openspec_cs
35104
npm run example
36105
```
37106

38-
## 文档
107+
## 近期变更
108+
109+
### 2026-04-21 - 添加 review-commands 技能
110+
111+
为 phSpec 项目添加各环节制品检查的审查技能，包括规格审查、代码审查和设计审查。
112+
113+
**新增能力**:
114+
- `/phsx:review-spec` - 规格质量审查
115+
- `/phsx:review-code` - 代码规范合规性审查
116+
- `/phsx:review-design` - 设计一致性审查
117+
- 增强 `/phsx:verify` 命令
118+
119+
详细记录：[Change Log](./changelog.md#2026-04-21---添加-review-commands-技能)
120+
121+
## 参考资源
39122

40-
详细文档请参考 [OpenSpec GitHub](https://github.com/Fission-AI/OpenSpec)
123+
- [OpenSpec GitHub](https://github.com/Fission-AI/OpenSpec)
124+
- [Change Log](./changelog.md) - 项目变更记录
125+
- [cc-spex](#) - 内部 Spec-Kit 变更管理工具（参考实现）

0 commit comments

Comments
 (0)