Skip to content

Commit 265f722

Browse files
committed
add related-file check matrix
1 parent fa1f435 commit 265f722

12 files changed

Lines changed: 168 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ npx devcodex init --claude # Claude Code
112112

113113
- **意图优先**:当用户看起来切到新需求时,先基于上下文判断意图;只有意图不清晰时才用关键词辅助,而不是反过来。
114114
- **边界先确认**:若已判断为新需求切换,且当前工作区还有未提交变更,会先提醒是否应先提交当前变更。
115+
- **高联动默认联查**:当任务涉及控制面规则、模板、接口契约/验证产物、工作区真相源/部署副本或发布口径变更时,会默认联查相关文件;若同时命中多真相源同步或模板-示例-校验链,会升级为交叉验证或 `CRS`。
115116
- **官方资料优先**:涉及平台能力、框架 API、版本兼容性或工具语义判断时,优先读取官方文档,再降级到其他资料。
116117
- **提交标题收短**:用户要求提交时,DevCodex 会优先生成一句简洁的 commit subject,而不是把整段会话摘要塞进标题。
117118

‎changelogs/unreleased.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@
88

99
## 2026-05-26
1010

11+
- 统一联查矩阵与相关文件检查规则收口:
12+
- 在 `instructions/01-common.instructions.md` 上提“统一联查矩阵(C11 扩展)”,定义 `L1/L2/L3` 联查级别、四类工作流最小动作与五类高联动场景默认联查清单
13+
- 为 `dev / fix / analyze` 工作流补齐最小联查适配动作,并明确 `audit` 对应 `L3 强联查`
14+
- 补充 `skills/dev-default`、`skills/fix-default`、`skills/analyze-research`、`skills/audit-common` 的联查矩阵映射
15+
- 扩展 `scripts/validate.js` 的联查矩阵语义探针,并同步 README 与 `website/docs/guide/development.md` 的用户面说明
16+
- 已完成 `.github/.claude` 部署同步,`node scripts/validate.js`、`node scripts/test-hooks-runtime.js`、`node scripts/test-mcp-servers.js`、`npm test` 全部通过
17+
1118
- 模板链防偏移能力增强:
1219
- 强化 `requirement.prompt.md`:补入需求类型判定、核心定义、作用域与边界判定、风险与开放问题、当前阶段结论,并要求 Markdown 需求文档包含 `## 目录导航`
1320
- 强化 `technical-design.prompt.md`:补入“关联目标文档”显式锚点,以及“实施映射与范围边界 / 偏移触发器”

‎instructions/01-common.instructions.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,43 @@ applyTo: "**"
6464
| C17 | 过程改进记录 | 用户建议的执行策略经 AI 确认更优时,必须立即追加一条 PI 条目到 `data/process-improvements.md`(不得询问是否记录),并标注是否已纳入规范 |
6565
| C19 | 确认后前置复审 | 每次用户明确确认后、进入下一阶段前,必须先对当前已确认产物做 1 轮轻量前置复审,并显式输出结果;控制面 / 多文件联动 / 真相源同步 / 模板-示例-校验链场景必须追加交叉验证;若发现阻断性问题,先修正并告知用户,再重新确认;无阻断问题方可推进 |
6666

67+
## 统一联查矩阵(C11 扩展)
68+
69+
> 目的:把“相关文件一起检查”从分散规则收口成统一入口。C11 仍是总约束;本节定义“默认联查什么、何时升级强度”。
70+
71+
### 联查级别
72+
73+
| 级别 | 含义 | 最低动作 |
74+
|:----:|------|---------|
75+
| L1 最小联查 | 当前文件 + 直接引用/直接真相源 | 检查直接调用、直接引用路径、当前用户面说明 |
76+
| L2 标准联查 | 同层联动文件 + 上下游说明文件 | 追加同层规则/模板/文档/验证脚本联查 |
77+
| L3 强联查 | 交叉验证 / CRS / 多真相源 / 部署副本 | 追加交叉验证、CRS、部署副本、校验链或定向 audit |
78+
79+
### 工作流最小动作
80+
81+
| 工作流 | 默认级别 | 最小动作 |
82+
|--------|:--------:|---------|
83+
| `dev` | L1 | 当前文件 + 直接引用/真相源;命中高联动场景默认升为 L2 |
84+
| `fix` | L2 | 保持“三步扫描”,并在高联动场景按 L3 处理 |
85+
| `analyze` | L1→L2 | 先提取关键词、建立关联文件集合;收敛前必须补一次 CRS |
86+
| `audit` | L3 | 继续使用 CRS / G3 / PCV,视为强联查路径 |
87+
88+
### 高联动场景默认联查清单
89+
90+
| 场景 | 默认联查文件族 | 默认级别 | 升级条件 |
91+
|------|---------------|:--------:|---------|
92+
| 控制面规则变更 | `instructions/`、`skills/`、`prompts/`、`hooks/`、`scripts/validate.js` | L2 | 涉及多真相源或部署副本 → L3 |
93+
| 模板变更 | `prompts/`、对应 `skills/`、对应 `instructions/`、`scripts/validate.js`、样本/示例文档 | L2 | 命中模板-示例-校验链 → L3 |
94+
| 接口契约 / 验证产物变更 | 技术方案、目标接口文档、`.http`、`.cjs`、调用方说明 | L2 | 对外契约 + 多端联调 → L3 |
95+
| 工作区真相源 / 部署副本 / 分发链变更 | `index.js`、`mcp/`、`hooks/_runtime/`、`README.md`、Profile、`.github/`、`.claude/` | L3 | 默认即强联查 |
96+
| 发布 / 版本 / changelog / profile 口径变更 | `package.json`、`plugin.json`、`CHANGELOG.md`、`changelogs/`、`README.md`、Profile、必要公告文档 | L2 | 多真相源口径同步 → L3 |
97+
98+
### 升级规则
99+
100+
- 命中多文件联动 / 多真相源同步 / 模板-示例-校验链 / 部署副本场景时,不得停留在 L1
101+
- 命中 C19 的交叉验证条件时,至少按 L3 处理
102+
- `document-sync`、`impact-review`、`api-verification` 继续作为联查子动作使用,不重写为平行机制
103+
67104
## 全自动模式 C02 豁免
68105

69106
当用户选择 `@devcodex-auto`(全自动模式)时:

‎instructions/10-dev.instructions.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,19 @@ CP1(需求确认)→ PR-1 内部自检 → CP2(方案确认)→ plan-rev
109109
2. `.cjs`
110110
3. 其他执行型验证脚本
111111

112+
### 统一联查矩阵(dev 最小动作)
113+
114+
- `dev` 默认按 **L1 最小联查** 执行:当前文件 + 直接引用/直接真相源
115+
- 高联动场景默认升为 L2 标准联查
116+
- 命中以下任一高联动场景时,默认升为 **L2 标准联查**:
117+
- 控制面规则变更(`instructions / skills / prompts / hooks / validate.js`)
118+
- 模板变更
119+
- 接口契约 / 验证产物变更
120+
- 工作区真相源 / 部署副本 / 分发链变更
121+
- 发布 / 版本 / changelog / profile 口径变更
122+
- 若同时涉及多真相源同步、模板-示例-校验链或部署副本,必须升级为 **L3 强联查**,并按 C19 追加交叉验证
123+
- `document-sync`、`impact-review`、`api-verification` 继续作为联查子动作使用,不替代统一联查矩阵
124+
112125
### 跨服务需求处理(CP1 前确认)
113126

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

‎instructions/11-fix.instructions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,17 @@ CP1(问题确认)→ CP2(方案确认)→ [impact-review] → [CP3] →
7676
2. **数据联动扫描** — 上下游数据流是否受影响(如:修复字段名 → grep 引用该字段的模型/路由/视图)
7777
3. **grep 零残留复核** — 确认无残留引用(如:`grep -r "旧名称" --include="*.js"` 确认零结果)
7878

79+
## 统一联查矩阵映射(fix)
80+
81+
- fix 默认按 **L2 标准联查** 起步
82+
- `fix` 默认按 **L2 标准联查** 起步;“修复三步必做”即是 fix 的最小联查动作
83+
- 命中以下场景时,必须升级为 **L3 强联查**:
84+
- 控制面规则或流程边界修复
85+
- 多真相源 / 多文件联动
86+
- 模板、示例与自动校验链联动
87+
- 工作区真相源 / 部署副本 / 分发链修复
88+
- `impact-review`、`document-sync`、`api-verification` 继续作为联查子动作使用,不替代三步扫描本身
89+
7990
## 执行约束
8091

8192
- 编码后必须运行 lint/typecheck/test;error 最多 2 次迭代

‎instructions/13-analyze.instructions.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@ applyTo: "**"
3535
- 未收敛时自动进入下一轮,**不询问用户**
3636
- 禁止提前收敛:不得在未达到最少轮次时输出"已收敛"结论
3737

38+
### 相关文件联查(analyze-lite)
39+
40+
- `analyze` 不直接复用完整 `audit` 流程,但必须补足最小联查动作
41+
- 至少执行以下步骤:
42+
1. 提取本轮分析问题的核心关键词
43+
2. 建立关联文件集合(代码、规则、文档、验证产物,按问题类型选取)
44+
3. 分析过程中若发现高联动场景,默认升为 **L2 标准联查**
45+
4. 收敛前必须再跑一次 `CRS`,确认关联文件集合没有遗漏
46+
- 若命中控制面、多真相源、模板-示例-校验链或单轮发现 ≥5 条 / 出现 🔴 问题,必须主动建议升级为 `audit`
47+
3848
> ℹ️ **analyze vs audit 的差异**:
3949
> - `analyze` — 聚焦**特定问题/结论**,不使用维度框架,轻量多轮(≥3 轮,连续 2 轮无新发现后收敛)
4050
> - `audit` — 使用**完整维度框架**(G1~G5 + 专属维度),覆盖范围更广;收敛条件:连续 3 轮零发现(不区分定向/全面,见 `12-audit §多轮收敛规则`)

‎scripts/validate.js‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -895,12 +895,77 @@ function checkV21() {
895895
'前置复审结果:✅ 无阻断,可进入下一阶段'
896896
]
897897
},
898+
{
899+
file: 'instructions/01-common.instructions.md',
900+
needles: [
901+
'统一联查矩阵(C11 扩展)',
902+
'L1 最小联查',
903+
'L2 标准联查',
904+
'L3 强联查',
905+
'控制面规则变更'
906+
]
907+
},
908+
{
909+
file: 'instructions/10-dev.instructions.md',
910+
needles: [
911+
'统一联查矩阵(dev 最小动作)',
912+
'高联动场景默认升为 L2 标准联查',
913+
'L3 强联查'
914+
]
915+
},
916+
{
917+
file: 'instructions/11-fix.instructions.md',
918+
needles: [
919+
'统一联查矩阵映射(fix)',
920+
'fix 默认按 **L2 标准联查** 起步',
921+
'工作区真相源 / 部署副本 / 分发链修复'
922+
]
923+
},
924+
{
925+
file: 'instructions/13-analyze.instructions.md',
926+
needles: [
927+
'相关文件联查(analyze-lite)',
928+
'建立关联文件集合',
929+
'收敛前必须再跑一次 `CRS`'
930+
]
931+
},
898932
{
899933
file: 'skills/fix-default/SKILL.md',
900934
needles: [
901935
'模板/示例不可直接执行',
902936
'自动化校验假绿'
903937
]
938+
},
939+
{
940+
file: 'skills/dev-default/SKILL.md',
941+
needles: [
942+
'统一联查矩阵(F-25)',
943+
'默认升为 L2 标准联查',
944+
'高联动场景不得只做单文件修改'
945+
]
946+
},
947+
{
948+
file: 'skills/fix-default/SKILL.md',
949+
needles: [
950+
'统一联查矩阵视为 L2 起步',
951+
'必须升为 L3'
952+
]
953+
},
954+
{
955+
file: 'skills/analyze-research/SKILL.md',
956+
needles: [
957+
'建立关联文件集合',
958+
'收敛前再跑一次 CRS',
959+
'统一联查矩阵(research 最小动作)'
960+
]
961+
},
962+
{
963+
file: 'skills/audit-common/SKILL.md',
964+
needles: [
965+
'统一联查矩阵映射(audit = L3)',
966+
'L3 强联查',
967+
'不被其他轻量联查规则替代'
968+
]
904969
}
905970
]
906971

‎skills/analyze-research/SKILL.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,17 @@ description: 技术调研子类型规范 — 技术选型/可行性评估/根因
2626
|------|------|
2727
| 1 | 明确调研问题(一句话核心问题) |
2828
| 2 | 确认调研范围(深度 + 技术栈约束) |
29-
| 3 | 收集信息(profile + 源码 + 依赖文档) |
29+
| 3 | 收集信息(profile + 源码 + 依赖文档)并建立关联文件集合 |
3030
| 4 | 分析评估(按调研类型,至少 3 轮) |
31-
| 5 | PCV(收敛后汇总验证,含合理性 + 可实施性 + 收益) |
32-
| 6 | 输出明确结论(禁止模糊结论) |
33-
| 7 | 输出调研报告 |
31+
| 5 | 收敛前再跑一次 CRS,确认关联文件集合无遗漏 |
32+
| 6 | PCV(收敛后汇总验证,含合理性 + 可实施性 + 收益) |
33+
| 7 | 输出明确结论(禁止模糊结论) |
34+
| 8 | 输出调研报告 |
35+
36+
## 统一联查矩阵(research 最小动作)
37+
38+
- `research` 默认执行 analyze-lite 联查:关键词提取 → 关联文件集合 → 收敛前再跑一次 CRS
39+
- 命中控制面、多真相源、模板-示例-校验链或单轮发现 ≥5 条 / 出现 🔴 问题时,应主动建议升级到 `audit`
3440

3541
## 各类型输出格式
3642

‎skills/audit-common/SKILL.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,12 @@ description: 审查公共维度 G0~G5 — 所有 audit 子类型必先执行的
3030
| G4 格式规范性 | 标题层级正确,代码块有语言标记,表格对齐 | 🟡 |
3131
| G5 链接有效性 | 内部/外部链接可访问,锚点存在 | 🟡 |
3232

33+
## 统一联查矩阵映射(audit = L3)
34+
35+
- `audit` 天生对应统一联查矩阵的 **L3 强联查**
36+
- `CRS / G3 / PCV` 继续作为 audit 的主路径,不降级、不被其他轻量联查规则替代
37+
- 其他工作流升级为 L3 时,应向 audit 的“关联文件全覆盖 + 收敛门禁”靠拢,而不是反过来弱化 audit
38+
3339
## 关联文件发现(CRS — 收敛前必须执行)
3440

3541
> 🔴 **CRS 是收敛的前置门禁**:宣告收敛前,必须完成关联文件发现扫描,确认审查范围已覆盖所有引用相同概念的文件。

‎skills/dev-default/SKILL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ dev 工作流未匹配其他子类型时的默认路径,适用于:新功能
2727

2828
**回归扫描(F-19)**:修改已有文件时,完成后须对该文件涉及的调用路径执行最小范围 grep 确认无残留引用问题;纯新增文件不触发。
2929

30+
**统一联查矩阵(F-25)**:命中控制面规则、模板、接口契约/验证产物、工作区真相源/部署副本、发布口径等高联动场景时,默认升为 L2 标准联查;若同时涉及多真相源同步或模板-示例-校验链,升级为 L3 强联查并追加交叉验证。
31+
3032
**错误处理验证(F-21)**:实施完成后须验证边界/异常路径(如空值/权限拒绝/超时)均有处理,不得只验证正常路径。
3133

3234
**调试清理(F-20)**:执行完成后须检查并清除 console.log / 临时注释 / TODO 标注(业务 TODO 转为 issue 跟踪)。
@@ -46,6 +48,7 @@ dev 工作流未匹配其他子类型时的默认路径,适用于:新功能
4648
- 三个 CP 必须按序获得用户确认,禁止合并跳过([C02](../../instructions/01-common.instructions.md))
4749
- PR-1 在 CP2 前做 AI 内部自检,PR-2~PR-7 在 CP2→CP3 之间做详细验证(`dev-plan-review` 两阶段流程)
4850
- 执行阶段结束后触发:`api-verification`(若涉及接口)→ `document-sync` → **轻量复审收敛**(N6,内部包含方案一致性验证)
51+
- 高联动场景不得只做单文件修改;至少要同步直接真相源与同层联动文件
4952
- `impact-review` 仅由 PR-5②(跨模块架构依赖变更)触发,position:plan-review 之后、CP3 之前
5053
- N4 只确认实施计划,不重复技术方案中的架构决策、接口论证和兼容性主说明;`05-实施进度.md` 仅在任务跨多轮、存在明确阻塞或用户要求持续跟踪时启用
5154
- 关键 Markdown 产物(需求 / 方案 / 实施计划 / 实施进度 / 阅读型文档 / README)必须包含 `## 目录导航`;`.http / .cjs` 不适用

0 commit comments

Comments
 (0)