Skip to content

Commit fa1f435

Browse files
committed
strengthen template anti-drift guardrails
1 parent 18572a3 commit fa1f435

13 files changed

Lines changed: 513 additions & 56 deletions

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ npx devcodex init --claude # Claude Code
5454
├── instructions/ ← Instructions 约束(12 个,含全部工作流规则)
5555
├── agents/ ← Copilot 自定义 Agent(v1.9.8 起恢复默认分发)
5656
├── skills/ ← Skill 详细检查标准(35 个,按需读取)
57-
├── prompts/ ← Prompt 模板(25 个)
57+
├── prompts/ ← Prompt 模板(26 个)
5858
├── hooks/ ← 宿主生命周期 Hook 配置与运行时
5959
│ ├── devcodex.lifecycle.json
6060
│ └── _runtime/
@@ -212,7 +212,7 @@ devcodex/
212212
├── agents/ # Agent 源文件;Copilot 端默认分发,Claude Code 端不分发
213213
├── instructions/ # 全局 Instructions(12 个,含工作流规则摘要,自动注入)
214214
├── skills/ # Skill 详细检查标准(35 个,按 01-common §按需读取表 路由读取)
215-
├── prompts/ # Prompt 模板(25 个)
215+
├── prompts/ # Prompt 模板(26 个)
216216
├── hooks/ # Workspace Hooks 配置与分发到 `.github/hooks/_runtime/` 的运行时
217217
├── data/ # 运行时数据模板(分发到目标项目的空骨架)
218218
│ ├── README.md

‎changelogs/unreleased.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,17 @@
88

99
## 2026-05-26
1010

11-
_当前无未发布变更。下一批开发/修复默认继续在此处追加。_
11+
- 模板链防偏移能力增强:
12+
- 强化 `requirement.prompt.md`:补入需求类型判定、核心定义、作用域与边界判定、风险与开放问题、当前阶段结论,并要求 Markdown 需求文档包含 `## 目录导航`
13+
- 强化 `technical-design.prompt.md`:补入“关联目标文档”显式锚点,以及“实施映射与范围边界 / 偏移触发器”
14+
- 强化 `implementation-plan.prompt.md` 与 `implementation-progress.prompt.md`:补入分批执行策略、关键实施约束、独立验证方式、阻塞恢复字段与回滚触发条件
15+
- 文档模板链补强:
16+
- 新增 `prompts/general-doc.prompt.md` 通用文档模板
17+
- 收口 `project-readme.prompt.md` 的项目类型分流,避免默认偏开源 npm 库场景
18+
- 收口 `light-api-doc.prompt.md` 的联调可用性,补入 `curl` 请求示例、成功响应和错误响应示例
19+
- 规则与校验链同步:
20+
- `skills/dev-docs`、`skills/dev-default`、`instructions/10-dev.instructions.md` 已统一要求 Markdown 阅读型文档具备目录导航,并要求 CP2 技术方案显式引用目标文档路径 / 模式 / 契约范围
21+
- `scripts/validate.js` 已补模板语义探针与资产计数联动校验
22+
- 部署与验证:
23+
- 已同步工作区 `.github/` 与 `.claude/`
24+
- `node scripts/validate.js`、`node scripts/validate-profile.js`、`node scripts/test-hooks-runtime.js`、`node scripts/test-mcp-servers.js`、`npm test` 全部通过

‎instructions/10-dev.instructions.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,9 +89,26 @@ CP1(需求确认)→ PR-1 内部自检 → CP2(方案确认)→ plan-rev
8989

9090
1. 仅对契约驱动型需求启用,不得推广到所有 dev 任务
9191
2. 目标文档属于 CP2 输入的一部分,不替代 `02-技术方案.md`
92-
3. CP2 技术方案必须显式说明如何以目标文档为最终契约锚点
92+
3. CP2 技术方案必须显式说明如何以目标文档为最终契约锚点,并至少写清:目标文档路径、文档模式(`light-api` / `frontend-api`)与本方案引用的契约范围
9393
4. CP3 与执行阶段的任务拆分、验证方式、回滚路径必须能追溯到目标文档
9494

95+
### Markdown 文档可读性要求
96+
97+
当 dev 工作流产出或更新以下 Markdown 文档时,必须补 `## 目录导航`:
98+
99+
1. `01-需求概述.md`
100+
2. `02-技术方案.md`
101+
3. `04-实施计划.md`
102+
4. `05-实施进度.md`(若存在)
103+
5. `README.md`
104+
6. `light-api` / `frontend-api` / `general-doc` 等阅读型文档
105+
106+
不适用对象:
107+
108+
1. `.http`
109+
2. `.cjs`
110+
3. 其他执行型验证脚本
111+
95112
### 跨服务需求处理(CP1 前确认)
96113

97114
当需求涉及多个服务时,须在 CP1 输出前完成以下判断:

‎prompts/general-doc.prompt.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
agent: agent
3+
description: 通用文档模板,用于生成架构文档、开发指南、迁移指南、治理说明等 Markdown 文档
4+
applyTo: .devcodex/**
5+
---
6+
# 通用文档模板
7+
8+
> **触发**: `dev-docs/SKILL.md` 的非契约驱动型文档场景
9+
> **适用**: 架构文档 / 开发指南 / 迁移指南 / 治理说明 / 运行手册
10+
> **要求**: 生成的 Markdown 文档必须包含 `## 目录导航`
11+
12+
---
13+
14+
## 文档头部
15+
16+
```markdown
17+
# <文档名称>
18+
19+
> **文档类型**: architecture / guide / migration / governance / runbook
20+
> **适用对象**: <谁会阅读这份文档>
21+
> **适用范围**: <模块 / 服务 / 工作区>
22+
> **更新时间**: YYYY-MM-DD
23+
```
24+
25+
## 目录导航
26+
27+
```markdown
28+
## 目录导航
29+
30+
- [1. 文档目的](#1-文档目的)
31+
- [2. 适用范围](#2-适用范围)
32+
- [3. 前置条件](#3-前置条件)
33+
- [4. 核心内容](#4-核心内容)
34+
- [5. 操作步骤 / 使用方式](#5-操作步骤--使用方式)
35+
- [6. 风险与注意事项](#6-风险与注意事项)
36+
- [7. 常见问题](#7-常见问题)
37+
- [8. 参考资料](#8-参考资料)
38+
```
39+
40+
## 1. 文档目的
41+
42+
> 说明这份文档解决什么问题,适合谁在什么情况下阅读。
43+
44+
## 2. 适用范围
45+
46+
- 服务 / 模块:
47+
- 环境:
48+
- 不适用范围:
49+
50+
## 3. 前置条件
51+
52+
- 依赖:
53+
- 权限:
54+
- 工具 / 环境:
55+
56+
## 4. 核心内容
57+
58+
> 按文档类型写主体内容。可使用二级或三级小节,但不要把所有内容堆成一段长文本。
59+
60+
## 5. 操作步骤 / 使用方式
61+
62+
> 适用于开发指南、迁移指南、运行手册等;纯说明类文档可标 `N/A`。
63+
64+
1.
65+
2.
66+
3.
67+
68+
## 6. 风险与注意事项
69+
70+
- 风险 1:
71+
- 风险 2:
72+
73+
## 7. 常见问题
74+
75+
### Q1.
76+
77+
-
78+
79+
## 8. 参考资料
80+
81+
- 关联需求 / 方案:
82+
- 代码路径:
83+
- 外部资料:
84+
```
85+
86+
## 编写要求
87+
88+
1. 默认使用调用方或读者视角写,不把实现细节塞满正文
89+
2. Markdown 文档必须包含 `## 目录导航`
90+
3. 若文档本身成为后续实现锚点,应在正文中显式引用关联需求、方案或接口文档
91+
4. 仅保留与当前文档类型相关的章节;无关章节可标 `N/A`

‎prompts/implementation-plan.prompt.md‎

Lines changed: 53 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ applyTo: .devcodex/requirements/**
88
> **路径**: `.devcodex/requirements/<中文描述>/04-实施计划.md`
99
> **触发**: dev 工作流 CP3 阶段
1010
> ⚠️ 本模板只承接任务拆分、实施顺序、前置依赖、验证方式与回滚策略,不重复需求背景或技术方案中的设计论证。
11+
> ⚠️ 生成的 Markdown 实施计划文档必须在头部后补 `## 目录导航`。
1112
1213
## 计划模式
1314

@@ -30,6 +31,21 @@ applyTo: .devcodex/requirements/**
3031
> **状态**: 计划中 / 执行中 / 已完成
3132
```
3233

34+
## 目录导航
35+
36+
```markdown
37+
## 目录导航
38+
39+
- [§1 总览](#1-总览)
40+
- [§2 任务分解](#2-任务分解)
41+
- [§3 分批执行策略](#3-分批执行策略)
42+
- [§4 关键实施约束](#4-关键实施约束)
43+
- [§5 独立验证方式](#5-独立验证方式)
44+
- [§6 里程碑 / 实施顺序](#6-里程碑--实施顺序)
45+
- [§7 风险点、回滚触发与回滚方案](#7-风险点回滚触发与回滚方案)
46+
- [§8 验收清单](#8-验收清单)
47+
```
48+
3349
## §1 总览
3450

3551
> 一句话描述本次实施范围,强调“这次要怎么落地”,而不是重新解释“为什么这样设计”。轻计划摘要只保留最小顺序与验证信息;完整实施计划再展开里程碑与风险细节。
@@ -47,7 +63,35 @@ applyTo: .devcodex/requirements/**
4763
| T-02 | | T-01 | | | |
4864
| T-03 | | T-02 | | | |
4965

50-
## §3 里程碑 / 实施顺序
66+
## §3 分批执行策略(完整实施计划重点)
67+
68+
> 完整实施计划默认应写清分批策略;轻计划摘要可压缩为 1~3 条顺序说明,但不能缺失“先做什么、后做什么、为什么这样排”。
69+
70+
| 批次/阶段 | 包含任务 | 进入条件 | 完成条件 |
71+
|-----------|---------|---------|---------|
72+
| Batch 1 | | | |
73+
| Batch 2 | | | |
74+
75+
## §4 关键实施约束
76+
77+
> 仅记录影响实施顺序、切换条件和执行边界的关键约束;不要把通用背景再复制一遍。
78+
79+
- 技术约束:
80+
- 数据/兼容性约束:
81+
- 不能顺手扩展的边界:
82+
- 需要回 CP2 / CP1 的触发条件:
83+
84+
## §5 独立验证方式
85+
86+
> 完整实施计划默认需要独立验证方式。轻计划摘要也至少要说明“执行后如何独立确认这批变更真的成立”。
87+
88+
| 验证项 | 验证方式 | 通过标准 |
89+
|--------|---------|---------|
90+
| 模板/规则一致性 | | |
91+
| 样本映射 | | |
92+
| 自动化校验 | | |
93+
94+
## §6 里程碑 / 实施顺序
5195

5296
> 完整实施计划使用里程碑表表达阶段性验收;轻计划摘要可改为“实施顺序”列表,但仍要说明任务先后与阶段完成点。
5397
@@ -56,15 +100,21 @@ applyTo: .devcodex/requirements/**
56100
| M1 | T-01~T-02 | |
57101
| M2 | T-03~Tn | |
58102

59-
## §4 风险点与回滚
103+
## §7 风险点、回滚触发与回滚方案
60104

61105
> 轻计划摘要至少要写出回滚摘要;完整实施计划应写到可执行粒度:失败后撤回什么、恢复到什么状态、如何确认已恢复。
62106
63107
| 任务 | 风险 | 回滚方案 |
64108
|------|------|---------|
65109
| T-0X | | |
66110

67-
## §5 验收清单
111+
### §7.1 回滚触发条件
112+
113+
> 明确哪些情况出现时,应暂停后续批次、回退当前批或回到上游 CP 重新确认。
114+
115+
-
116+
117+
## §8 验收清单
68118

69119
- [ ] 所有任务完成
70120
- [ ] 关键路径单测通过

‎prompts/implementation-progress.prompt.md‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ applyTo: .devcodex/requirements/**
88
> **路径**: `.devcodex/requirements/<中文描述>/05-实施进度.md`
99
> **触发**: 实施阶段中间检查点
1010
> ⚠️ 条件触发:仅在任务跨多轮/多阶段、存在明确阻塞或用户要求持续跟踪时启用;且前提是已存在 `04-实施计划.md` 或等价任务切片。
11+
> ⚠️ 生成的 Markdown 实施进度文档必须在头部后补 `## 目录导航`。
1112
1213
---
1314

@@ -19,26 +20,42 @@ applyTo: .devcodex/requirements/**
1920
> **当前轮次**: R[N]
2021
```
2122

23+
## 目录导航
24+
25+
```markdown
26+
## 目录导航
27+
28+
- [进度总览](#进度总览)
29+
- [当前轮次工作](#当前轮次工作)
30+
- [阻塞与恢复](#阻塞与恢复)
31+
- [下一步](#下一步)
32+
- [变更记录](#变更记录)
33+
```
34+
2235
## 进度总览
2336

2437
> 只记录执行推进情况,不重复需求背景、技术方案正文或实施计划的完整任务定义。
2538
26-
| 任务 | 状态 | 完成时间 | 备注 |
27-
|------|:----:|---------|------|
28-
| T-01 | ✅ 完成 | | |
29-
| T-02 | 🔄 进行中 | | |
30-
| T-03 | ⏳ 待开始 | | |
39+
| 任务 | 状态 | 是否阻断主线 | 完成时间 | 备注 |
40+
|------|:----:|:------------:|---------|------|
41+
| T-01 | ✅ 完成 | 否 | | |
42+
| T-02 | 🔄 进行中 | 否 / 是 | | |
43+
| T-03 | ⏳ 待开始 | 否 | | |
3144

3245
**完成率**: X / N 任务(X%)
3346

3447
## 当前轮次工作
3548

3649
> 本轮完成了什么、推进到了哪里:
3750
38-
## 遇到的问题
51+
**本轮验证结果**:
52+
-
53+
54+
## 阻塞与恢复
3955

40-
| 问题 | 影响 | 处理方式 |
41-
|------|------|---------|
56+
| 问题/阻塞 | 是否阻断主线 | 责任方 | 预计解除时间 | 当前处理方式 | 下次检查点 |
57+
|------------|:------------:|--------|---------------|-------------|------------|
58+
| | 否 / 是 | | | | |
4259

4360
## 下一步
4461

0 commit comments

Comments
 (0)