Skip to content

Commit 5751698

Browse files
xinetzonexinetzone
committed
docs(five-dim-review): 建立交叉引用索引，落实体系自我治理机制
新增 framework-cross-reference-index.md：章节粒度引用关系登记、变更影响传播矩阵、版本一致性校验清单 完善全部六份文档的更新记录表，统一新增「是否影响其他文档」列，落实短期缓解建议 更新 framework-system-analysis.md 至 V1.2：短期/长期缓解建议均标记为已落地，依赖链图新增基础设施层
1 parent 90d1a47 commit 5751698

6 files changed

Lines changed: 286 additions & 7 deletions

File tree

‎apps/chaos/.agents/docs/references/five-dimension-review-framework/anti-pattern-detection-signals.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -290,10 +290,10 @@
290290

291291
### 更新记录
292292

293-
| 版本 | 日期 | 变更 |
294-
|------|------|------|
295-
| V1.0 | 2026-06-11 | 初始版本 |
296-
| V1.1 | 2026-06-11 | 移除 XMNN/Python 特定示例，替换为技术栈无关的通用描述 |
293+
| 版本 | 日期 | 变更 | 是否影响其他文档 |
294+
|------|------|------|-----------------|
295+
| V1.0 | 2026-06-11 | 初始版本 | 否（首次创建） |
296+
| V1.1 | 2026-06-11 | 移除 XMNN/Python 特定示例，替换为技术栈无关的通用描述 | 否（通用化使引用更稳定，无需下游同步） |
297297

298298
---
299299

‎apps/chaos/.agents/docs/references/five-dimension-review-framework/framework-cross-reference-index.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# 五维度评审框架：文档间交叉引用索引
2+
3+
> **用途**：记录五份文档之间的显式引用关系，为一致性维护和变更影响分析提供单一查询入口。
4+
>
5+
> **维护规则**：任一份文档发生章节级变更（增删/重编号/拆分/合并）后，必须同步更新本索引中受影响的条目。
6+
>
7+
> **生成日期**：2026-06-11
8+
>
9+
> **数据来源**：对五份文档全文的引用关系逐条提取与交叉验证。
10+
11+
---
12+
13+
## 一、文档元数据速览
14+
15+
| 文档 | 文件名 | 当前版本 | 在体系中的角色 | 最后更新 |
16+
|------|--------|----------|---------------|---------|
17+
| 评审模板 | `tech-proposal-review-template.md` | V1.0 | 工具——评审者直接填写的操作载体 | 2026-06-11 |
18+
| 使用说明书 | `review-template-usage-guide.md` | V1.0 | 指引——教评审者如何正确填写模板 | 2026-06-11 |
19+
| 设计哲学洞察 | `review-template-design-philosophy.md` | V1.0 | 原理——解释模板"为什么这样设计" | 2026-06-11 |
20+
| 反模式对照表 | `anti-pattern-detection-signals.md` | V1.1 | 知识库——可复用的反模式检测信号库 | 2026-06-11 |
21+
| 体系分析报告 | `framework-system-analysis.md` | V1.2 | 元层次——分析文档间关系与结构性矛盾 | 2026-06-11 |
22+
| 交叉引用索引 | `framework-cross-reference-index.md` | V1.0 | 基础设施——记录文档间显式引用关系，提供变更影响查询入口 | 2026-06-11 |
23+
24+
---
25+
26+
## 二、消费依赖链
27+
28+
```
29+
评审模板（工具） ── 被解释 ──→ 设计哲学洞察（原理）
30+
│ │
31+
├── 被指引 ──→ 使用说明书（指引） │
32+
│ │
33+
└── 被验证 ──→ 体系分析报告（元层次）
34+
│
35+
反模式对照表（知识库）── 被引用 ──┘
36+
```
37+
38+
### 依赖方向明细
39+
40+
| 上游文档（被依赖方） | 下游文档（依赖方） | 关系类型 |
41+
|---------------------|-------------------|---------|
42+
| 评审模板 | 使用说明书 | 说明书逐节指导模板的填写方法 |
43+
| 评审模板 | 设计哲学洞察 | 哲学洞察解释模板确认项的设计来源与意图 |
44+
| 评审模板 | 体系分析报告 | 分析报告以模板为核心评估体系的结构性矛盾 |
45+
| 反模式对照表 | 体系分析报告 | 分析报告引用反模式条目验证自指涉特性 |
46+
| 设计哲学洞察 | 体系分析报告 | 分析报告引用二分架构讨论维护熵增 |
47+
| 使用说明书 | 设计哲学洞察 | 哲学洞察中引用说明书的适用场景信息 |
48+
| 使用说明书 | 体系分析报告 | 分析报告中提及说明书的引用脆弱性 |
49+
50+
---
51+
52+
## 三、逐文档引用关系表
53+
54+
### 3.1 评审模板 → 被其他文档引用
55+
56+
> 角色：工具。模板本身不引用其他文档，但被其余四份文档引用。
57+
58+
| 模板章节 | 被引用方 | 引用方章节 | 引用性质 |
59+
|----------|---------|-----------|---------|
60+
| §1.1 问题定位准确性（确认项表） | 使用说明书 | §二 维度一填写指南 | 填写指导——逐条解释如何评估模板 §1.1 的每个确认项 |
61+
| §1.2 问题深度（确认项表） | 使用说明书 | §二 维度一填写指南 | 填写指导——解释"演变路径""模式识别"等确认项的判断逻辑 |
62+
| §1.2 第4项 "是否揭示了问题形成的演变路径" | 设计哲学洞察 | §三 案例一 | 设计来源——说明该确认项如何从 XMNN 案例中提炼 |
63+
| §1.3 评审者补充 | 使用说明书 | §二 维度一填写指南 | 填写指导——提醒不要在补充区写方案建议 |
64+
| §2.1 技术选型合理性（确认项表） | 使用说明书 | §二 维度二填写指南 | 填写指导——评估技术选型时的注意点 |
65+
| §2.2 架构设计质量（确认项表） | 使用说明书 | §二 维度二填写指南 | 填写指导——评估架构设计质量的方法 |
66+
| §2.2 整体确认项 | 设计哲学洞察 | §一 维度序列 | 认知递进链——"方案设计"在五维度序列中的定位 |
67+
| §2.3 潜在风险识别（风险表） | 使用说明书 | §二 维度二填写指南 | 填写指导——说明风险表的主动识别用法及示例 |
68+
| §3.1 主链路覆盖（确认项表） | 使用说明书 | §二 维度三填写指南 | 填写指导——检查主链路覆盖的方法 |
69+
| §3.2 边界情况覆盖（6类预设场景） | 使用说明书 | §二 维度三填写指南 | 填写指导——逐条说明6类边界场景何时标记"需要补充" |
70+
| §3.2 6类预设边界场景 | 设计哲学洞察 | §三 案例二 | 设计来源——说明6类场景来自高频遗漏点的提炼 |
71+
| §3.3 评审者补充 | 使用说明书 | §二 维度三填写指南 | 填写指导——提醒不要替作者补充测试方案 |
72+
| §4.1 收益声明清单 | 使用说明书 | §二 维度四填写指南 | 填写指导——说明如何逐条提取和评估收益声明 |
73+
| §4.2 第1项 "量化指标是否具体" | 设计哲学洞察 | §三 案例四 | 设计来源——说明量化锚点要求的来源与检测方法 |
74+
| §4.2 第3项 "是否区分了消除阻碍和实现能力" | 设计哲学洞察 | §三 案例三 | 设计来源——说明该确认项如何从"论证过度"手法中提炼 |
75+
| §5.1 文档综合质量（评分表） | 使用说明书 | §二 维度五填写指南 | 填写指导——综合前四个维度打分的逻辑 |
76+
| §5.3 分阶段行动建议 | 使用说明书 | §二 维度五填写指南 | 填写指导——四阶段建议的填写粒度与示例 |
77+
| §5.4 评审结论 | 使用说明书 | §二 维度五填写指南 | 填写指导——三种结论的使用条件说明 |
78+
| 整体（五维度框架） | 设计哲学洞察 | §一 维度序列 | 认知递进链——论证五个维度的排列逻辑 |
79+
| 整体（确认项+补充项二分） | 设计哲学洞察 | §二 二分架构 | 架构解释——说明两层结构的设计意图与机制 |
80+
| 整体（三元评估标记 ✅/⚠️/❌） | 设计哲学洞察 | §二 三元评估标记 | 设计解释——说明三元优于二元的原因 |
81+
| 整体 | 体系分析报告 | §一 消费依赖链 | 体系分析——将模板定位为依赖链的起点 |
82+
| 整体 | 体系分析报告 | §三 维护熵增 | 体系分析——讨论确认项膨胀的结构性矛盾 |
83+
84+
---
85+
86+
### 3.2 使用说明书 → 引用其他文档 / 被其他文档引用
87+
88+
> 角色：指引。引用模板和设计哲学，被哲学洞察和体系分析引用。
89+
90+
#### 3.2.1 使用说明书对外引用
91+
92+
| 说明书章节 | 被引用文档 | 被引用章节 | 引用性质 |
93+
|-----------|-----------|-----------|---------|
94+
| 开头 "前置阅读" | 评审模板 | 整体 | 建议读者先浏览模板再读说明书 |
95+
| §一 适用场景 表格 | 设计哲学洞察 | §四 适用度矩阵 | 与哲学洞察中的适用度矩阵互补——说明书侧重操作场景，哲学洞察侧重适用度评级 |
96+
| §二 维度一填写指南 | 评审模板 | §1.1, §1.2, §1.3 | 逐一指导模板 §1 各子章节的填写方法 |
97+
| §二 维度二填写指南 | 评审模板 | §2.1, §2.2, §2.3, §2.4 | 逐一指导模板 §2 各子章节的填写方法 |
98+
| §二 维度三填写指南 | 评审模板 | §3.1, §3.2, §3.3 | 逐一指导模板 §3 各子章节的填写方法 |
99+
| §二 维度四填写指南 | 评审模板 | §4.1, §4.2, §4.3 | 逐一指导模板 §4 各子章节的填写方法 |
100+
| §二 维度五填写指南 | 评审模板 | §5.1, §5.2, §5.3, §5.4 | 逐一指导模板 §5 各子章节的填写方法 |
101+
| §五 模板定制指南 | 设计哲学洞察 | §四 适用边界 | 与适用度矩阵共同构成定制建议 |
102+
103+
#### 3.2.2 使用说明书被其他文档引用
104+
105+
| 说明书章节 | 引用方 | 引用方章节 | 引用性质 |
106+
|-----------|--------|-----------|---------|
107+
| §三 评审流程建议 | 体系分析报告 | §五 外循环 | 分析报告中"评审者会花30分钟填写模板"的假设即来自说明书的流程时间建议 |
108+
| §四 与 Code Review 的关系 | 体系分析报告 | §五 外循环 | 该衔接说明中的假设在真实团队评审中可能被打破 |
109+
| §五 模板定制指南 | 设计哲学洞察 | §四 适用边界 | 定制建议与适用度矩阵相互补充 |
110+
111+
---
112+
113+
### 3.3 设计哲学洞察 → 引用其他文档 / 被其他文档引用
114+
115+
> 角色：原理。解释模板设计意图，被体系分析引用。
116+
117+
#### 3.3.1 设计哲学洞察对外引用
118+
119+
| 哲学洞察章节 | 被引用文档 | 被引用章节 | 引用性质 |
120+
|-------------|-----------|-----------|---------|
121+
| §一 维度序列 | 评审模板 | 整体（五维度排列） | 解释五个维度的认知递进逻辑 |
122+
| §二 "确认项"与"补充项"的二分架构 | 评审模板 | 整体（确认项+补充项结构） | 解释两层结构的设计机制和知识沉淀意图 |
123+
| §二 三元评估标记 | 评审模板 | 整体（✅/⚠️/❌ 标记体系） | 解释三元优于二元的原因 |
124+
| §三 案例一 | 评审模板 | §1.2 第4项 | 追溯"演变路径"确认项的来源 |
125+
| §三 案例二 | 评审模板 | §3.2 6类边界场景 | 追溯"预设边界场景"确认项的来源 |
126+
| §三 案例三 | 评审模板 | §4.2 第3项 | 追溯"消除阻碍 vs 实现能力"确认项的来源 |
127+
| §三 案例四 | 评审模板 | §4.2 第1项 | 追溯"量化锚点"确认项的来源 |
128+
| §四 适用边界 适用度矩阵 | 使用说明书 | §一 适用场景 | 补充适用度的评级维度（★） |
129+
| §四 误用一 "过度填充" | 使用说明书 | §二 维度一填写指南 | 纠正过度填写的倾向 |
130+
| §四 误用二 "把模板当审批关卡" | 使用说明书 | §五 模板定制指南 | 纠正过度严格的倾向 |
131+
132+
#### 3.3.2 设计哲学洞察被其他文档引用
133+
134+
| 哲学洞察章节 | 引用方 | 引用方章节 | 引用性质 |
135+
|-------------|--------|-----------|---------|
136+
| §二 二分架构 | 体系分析报告 | §二 线索一（自指涉——确认项+补充项） | 验证二分架构的自指涉特性 |
137+
| §二 二分架构（持续进化机制） | 体系分析报告 | §三 维护熵增（结构性矛盾） | 分析确认项累积与使用负担的矛盾 |
138+
| §三 四个关键检查项 | 体系分析报告 | §五 外循环（假设验证） | 分析这些来自单人深度分析的确认项在多样本下是否依然有效 |
139+
| §四 适用度矩阵 | 体系分析报告 | §五 外循环 | 讨论文档类型多样化后某些维度频繁标"不适用"的可能性 |
140+
141+
---
142+
143+
### 3.4 反模式对照表 → 引用其他文档 / 被其他文档引用
144+
145+
> 角色：知识库。独立的反模式库，被体系分析引用作为自指涉验证素材。
146+
147+
#### 3.4.1 反模式对照表对外引用
148+
149+
| 反模式对照表章节 | 被引用文档 | 被引用章节 | 引用性质 |
150+
|-----------------|-----------|-----------|---------|
151+
| 结尾 "关联文档" | 评审模板 | 整体 | 文档间导航引用 |
152+
| 结尾 "关联文档" | 设计哲学洞察 | 整体 | 文档间导航引用 |
153+
| 结尾 "关联文档" | 使用说明书 | 整体 | 文档间导航引用 |
154+
155+
#### 3.4.2 反模式对照表被其他文档引用
156+
157+
| 反模式对照表章节 | 引用方 | 引用方章节 | 引用性质 |
158+
|-----------------|--------|-----------|---------|
159+
| §2.1 静默失败传播 | 体系分析报告 | §二 线索三（自指涉——静默失败传播） | 将"底层变更不自动通知上层"映射为该反模式在体系自身的微缩版 |
160+
| §3.1 规则重复定义 | 体系分析报告 | §二 线索二（自指涉——规则重复定义） | 将"版本号在各文档独立维护"映射为该反模式在体系自身的微缩版 |
161+
| §1.1 工具模块膨胀 | 体系分析报告 | §三 维护熵增（推荐方向：定期收割） | 将"定期收割机制"定位为反膨胀策略的预防性应用 |
162+
163+
---
164+
165+
### 3.5 体系分析报告 → 引用其他文档 / 被其他文档引用
166+
167+
> 角色：元层次。作为体系自观察的产物，引用其余四份文档。
168+
169+
#### 3.5.1 体系分析报告对外引用
170+
171+
| 分析报告章节 | 被引用文档 | 被引用章节 | 引用性质 |
172+
|-------------|-----------|-----------|---------|
173+
| §一 消费依赖链 | 评审模板 | 整体 | 将模板定位为依赖链起点 |
174+
| §一 消费依赖链 | 使用说明书 | 整体 | 将说明书定位为模板的下游消费方 |
175+
| §一 消费依赖链 | 设计哲学洞察 | 整体 | 将哲学洞察定位为模板的解释层 |
176+
| §一 消费依赖链 | 反模式对照表 | 整体 | 将对照表定位为独立知识库 |
177+
| §一 缓解建议（长期） | 本索引文件 | 整体 | 本索引文件即为该建议的落地产物 |
178+
| §二 线索一 | 设计哲学洞察 | §二 二分架构 | 用"确认项+补充项"验证自指涉特性 |
179+
| §二 线索二 | 反模式对照表 | §3.1 规则重复定义 | 用"规则重复定义"验证自指涉特性 |
180+
| §二 线索三 | 反模式对照表 | §2.1 静默失败传播 | 用"静默失败传播"验证自指涉特性 |
181+
| §三 结构性矛盾 | 设计哲学洞察 | §二 二分架构 | 讨论确认项膨胀的矛盾 |
182+
| §三 推荐方向 | 反模式对照表 | §1.1 工具模块膨胀 | 引用"工具模块膨胀"的反模式预防策略 |
183+
| §四 案例的不可替代价值 | 使用说明书 | §二 各维度填写指南 | 讨论说明书、设计哲学、对照表各自无法替代案例的价值 |
184+
| §五 外循环假设 | 使用说明书 | §三 评审流程建议 | 讨论"30分钟评审"假设在真实环境中的可行性 |
185+
186+
#### 3.5.2 体系分析报告被其他文档引用
187+
188+
> 体系分析报告是最后生成的元层次文档，目前不被其余四份文档引用。未来若其他文档新增"参见体系分析"的交叉引用，应在此处登记。
189+
190+
---
191+
192+
## 四、变更影响传播矩阵
193+
194+
当某份文档发生以下类型的变更时，需要同步检查并可能更新受影响的文档。
195+
196+
| 变更源 | 变更类型 | 可能受影响的文档及章节 |
197+
|--------|---------|---------------------|
198+
| 评审模板 | 新增/删除确认项 | 使用说明书 §二（对应维度的填写指南）；设计哲学洞察 §三（若涉及新增确认项的来源说明） |
199+
| 评审模板 | 确认项重新编号 | 使用说明书 §二（所有引用模板编号的填写指导）；设计哲学洞察 §三（案例中引用的具体确认项编号） |
200+
| 评审模板 | 修改维度排列顺序 | 设计哲学洞察 §一（认知递进链的论证）；使用说明书 §二（维度填写顺序） |
201+
| 评审模板 | 版本号变更 | 反模式对照表（关联文档引用）；本索引 §一（元数据表） |
202+
| 使用说明书 | 更新填写指导 | 设计哲学洞察 §四（适用边界，若指导与哲学原理不一致） |
203+
| 使用说明书 | 版本号变更 | 反模式对照表（关联文档引用）；本索引 §一 |
204+
| 设计哲学洞察 | 增补新的确认项来源说明 | 使用说明书 §二（若新来源暗示了新的填写注意点） |
205+
| 设计哲学洞察 | 版本号变更 | 本索引 §一 |
206+
| 反模式对照表 | 新增反模式条目 | 体系分析报告 §二（若新条目可映射为新的自指涉线索） |
207+
| 反模式对照表 | 版本号变更 | 本索引 §一 |
208+
| 体系分析报告 | 新增结构性发现 | 其他四份文档（若发现指向某文档的具体问题） |
209+
| 本索引 | 任意条目更新 | 无下游——本索引为引用关系的终点 |
210+
211+
---
212+
213+
## 五、版本一致性校验清单
214+
215+
每次任意文档发布新版本时，逐项检查以下内容：
216+
217+
| # | 检查项 | 验证方法 |
218+
|---|--------|---------|
219+
| 1 | 本索引 §一 元数据表中的版本号与实际文件一致 | 打开目标文件，确认文件内声明的版本号 |
220+
| 2 | 所有"关联文档"末尾引用指向的文件名仍然正确 | 逐文档检查末尾"关联文档"段落中的文件名 |
221+
| 3 | 模板章节编号未发生漂移 | 对比上一版本模板的目录结构 |
222+
| 4 | 使用说明书中的章节引用仍可定位 | 按说明书中的"模板 §X.Y"逐条验证模板对应章节是否存在 |
223+
| 5 | 设计哲学中案例引用的确认项编号未失效 | 按哲学洞察 §三 四个案例逐条验证模板中对应确认项 |
224+
| 6 | 体系分析报告中的反模式编号引用仍有效 | 按分析报告 §二 线索二/三验证反模式对照表中的对应条目 |
225+
| 7 | 无新增的跨文档引用未被本索引收录 | 全文搜索 `[.*\].*\.md` 模式，与本索引比对 |
226+
227+
---
228+
229+
## 六、维护记录
230+
231+
| 版本 | 日期 | 变更内容 | 是否影响其他文档 |
232+
|------|------|---------|-----------------|
233+
| V1.0 | 2026-06-11 | 初始版本——从五份文档中提取全部显式引用关系并结构化登记 | 否（首次创建） |
234+
235+
---
236+
237+
> **关联文档**：[tech-proposal-review-template.md]（评审工具）、[review-template-usage-guide.md]（使用指引）、[review-template-design-philosophy.md]（设计哲学）、[anti-pattern-detection-signals.md]（反模式对照表）、[framework-system-analysis.md]（体系分析报告）

0 commit comments

Comments
 (0)