📄 本页由源文件
rules/按需-Skill设计-跨文件协作.mdc自动投影生成（单一权威源）。请勿直接编辑本页。
按需-Skill设计-跨文件协作
本文件由
rules/AI行为规范.mdc§ Skill 设计哲学 / § 跨文件协作设计模式 引用触发；alwaysApply=false 节省常驻 Token。 触发场景：创建/重构 Skill、Skill 多文件改动、Skill 实施沉淀、跨 Skill 协作。
一、Skill 设计哲学（强制，2026-05-15 沉淀）
核心原则：确定性用代码，模糊性用 LLM。 来源：dev-flow v3 重构（2026-05-14）实战验证 + Anthropic Claude Code Hooks / 12-factor agents 共识。 框架原则与数据驱动落地手法的完整论述见
skills/dev-flow/references/core-principles.md§19 / §20。
1.1 Skill 创建/重构「决策清单」必答项
接在「先调研 → 决策清单 → 用户确认 → 实现」流程的「决策清单」环节。 列出本 Skill 涉及的所有规则/检查项，逐条标注「确定性（→ 脚本/lint/配置）」or「模糊性（→ 提示词/LLM）」：
| 规则/能力 | 类型 | 实现方式 | 兜底机制 |
|---|---|---|---|
| 例：检查文件存在 | 确定性 | bash [ -f ] | exit code |
| 例：检查 JSON 格式 | 确定性 | jq / ajv | exit code |
| 例：检查行数 / 命名规范 | 确定性 | lint 脚本 | exit code |
| 例：判断方案是否优雅 | 模糊性 | LLM | 用户决策 |
| 例：判断根因是否合理 | 模糊性 | LLM | 用户决策 |
任何标注为「确定性」的规则，必须有对应脚本/配置/Schema 兜底，不允许只写在 SKILL.md 提示词里。
1.2 反模式（违反即拒收）
- ❌ 把"某检查不可跳过"写成 SKILL.md 提示词依赖 AI 记忆，没有
.validated物理事实兜底 - ❌ 同一条规则在 N 个文档里重复维护（应该有「单一权威源」：脚本是真相，文档只引用不重复）
- ❌ 设计阶段没做拆分，先把所有规则全塞提示词，事后再重构（dev-flow v3 走的就是这条弯路，重构成本极高，应避免重蹈覆辙）
1.3 正确范式（dev-flow v3 已落地，可参考）
- 程序化优先：能进
config/gates.yaml/scripts/lints/的就不进提示词 - 单一权威源：脚本/配置是规则真相
- 物理事实兜底：
.validated由脚本原子创建，AI 不可绕过 - 元门控守护：用
refactor-gate.sh类脚本守护规则系统本身 - 数据驱动 + fallback：枚举/列表/映射类数据放 YAML（主路径）+ 保留硬编码 fallback（兜底）；详见
skills/dev-flow/references/core-principles.md§20.2 双层结构 + §20.3 配置驱动测试模式
二、跨文件协作设计模式（同形 ×2 promote，2026-05-15）
背景：Skill 多文件改动 / 跨 Skill 协作 / Skill 实施沉淀时，规则文档↔步骤文档↔脚本实现三方必须形成「单一权威源 + 双向引用」的协作网（源于同形 ×2 病灶提升 + 三层防线 P0/P1/P2 实战沉淀）。
2.1 强制套用清单（修改 ≥2 个文件且涉及规则/步骤/脚本协作时）
- 写入前问清楚：「这条规则的『真相』在哪个文件？」（脚本/YAML/Schema 永远优先于 markdown 提示词）
- A → B 引用，必须配 B → A 反向引用：自检命令是
grep -nE "B-keyword" A.md && grep -nE "A-keyword" B.md，任一为空 → 断链待修 - 落地后必须 grep 实测：禁止凭"我刚才说要做"的记忆当作"已经做了"，所有承诺必须用
grep/ls工具实测验证后才能宣告完成（与 § 验证行为规范 「承诺一致性必须 grep 实测」一致） - 脚本顶部注释也要双向引用：脚本是规则真相时，顶部注释里要明文写「← references/xxx.md §Y / steps/zzz.md §Z」，避免脚本被孤立修改
- 跨文档变更留迁移指向：源文件改动如果同时影响多个文档，必须在每个变更点留下「详见 X 文件 §Y」的反向跳板
2.2 反模式（违反即拒收）
- ❌ 在 ▶️ 选项里承诺「§A 与 §B 已建立呼应」，实际只读了 §A 的引用，没动手扩展 §B 的反向引用 → 单向断链
- ❌ 在 N 个文档里重复维护同一条规则的内容（应该有「单一权威源」：脚本是真相，文档只引用不重复）
- ❌ 按"自己刚写过 plan.md/devlog.md，肯定有"的记忆免去物理事实校验
2.3 参考实施案例（×2 已 promote）
- 案例 ×1：
knowledge-loop↔dev-flow的 sync 滞后检测协作 - 案例 ×2：
step-7-commit.md §K↔gate-validator.md §「dev-logs 物理事实兜底（P0/P1 闭环）」↔validate-output.sh / devlog-integrity-lint.sh三方双向引用闭环
三、引用回链（双向闭环）
- 主文件：
rules/AI行为规范.mdc§ Skill 设计哲学 / § 跨文件协作设计模式（保留 ≤5 行核心断言 + 引用本文件） - 框架原则：
skills/dev-flow/references/core-principles.md§19 / §20