--- name: audit-dimensions description: D1~D25 规范文件审查维度总览 — 规范库/specs 文件专属审查层 --- # Audit Dimensions Skill ## 适用范围 审查目标为**规范文件**（instructions/*.md、skills/**/SKILL.md、agents/*.agent.md、RULES.md 等 AI 指导文档）时加载本 Skill。 ## 维度总览（D1~D25） | 分组 | 维度 | 优先级 | |------|------|:------:| | A — 结构规范 | D1 文件结构 · D2 NODE_META/frontmatter 规范 · D3 路由语法正确性 | 🔴 | | B — 内容质量 | D4 内容完整性 · D5 跨文件一致性 · D6 示例可执行性 | 🔴/🟡 | | C — 可维护性 | D7 职责边界 · D8 版本标注 · D9 引用准确性 | 🔴/🟡 | | D — AI 执行性 | D10 指令明确性 · D11 冲突检测 · D12 路由正确性 | 🔴 | | E — 可扩展性 | D13 扩展点标注 · D14 租户覆盖支持 · D15 向后兼容 | 💡 | | F — 维度体系 | D16 维度编号唯一 · D17 优先级标注 · D18 AI-first 设计 | 🔴/🟡 | | G — 运维 | D19 废弃说明 · D20 变更历史 · D21 Markdown 渲染格式 | 🟡/🔴 | | H — 语义正确性 | D22 产品语义正确性 | 🔴 | | I — 跨客户端适配 | D23 Claude Code 适配层 · D24 客户端支持矩阵 · D25 记忆/报告 agent 字段 | 🔴 | ## 执行优先级分批 | 批次 | 维度 | 说明 | |------|------|------| | 🔴 第一批 | D1·D2·D3·D4·D5·D7·D9·D10·D11·D12·D16·D17·D21·D22·D23·D24·D25 | 强制，发现问题立即标记 | | 🟡 第二批 | D6·D8·D18·D19·D20 | 建议，不阻塞 | | 💡 第三批 | D13·D14·D15 | 改进，按 Token 预算执行 | ## 关键检查（D5 跨文件一致性） 新增子类型 spec 后必须核查三项（L1~L3）： - L1：`routing/SKILL.md` 路由表包含该子类型 - L2：`02-output-paths.instructions.md` 注册该子类型目录 - L3：对应 report 模板的子类型字段包含该子类型 --- ## 各维度检查项 ### A — 结构规范 **D1 文件结构 🔴** | # | 检查内容 | |:-:|---------| | 1 | `plugin.json` 注册的所有 `agents/*/` 和 `skills/*/` 文件是否实际存在 | | 2 | 每个 SKILL.md 是否有 YAML frontmatter（`name` + `description`）| | 3 | 每个 agent 文件是否有 `name`/`description`/`tools` 三字段 | | 4 | 所有 `prompts/*.prompt.md` 是否有 `agent`/`description`/`applyTo` frontmatter（注：`agent: agent` 为 VS Code Copilot prompt 的正确字段，非 `mode`）| | 5 | instructions 目录中是否存在无 `applyTo` 的文件（需添加）| **D2 frontmatter 规范 🔴** | # | 检查内容 | |:-:|---------| | 1 | agent frontmatter 中 `tools:` 列表是否符合 Copilot 平台支持的工具名（filesystem/terminal）| | 2 | DevCodex Skills 注释（``）中的 skill id 是否全部在 `plugin.json` 里注册 | | 3 | instructions 文件的 `applyTo` 是否正确（全局用 `**`，工作流专属用具体路径）| | 4 | Skills 注释里的 id 顺序是否与执行依赖顺序一致（core 类 skill 应排在前）| **D3 路由语法正确性 🔴** | # | 检查内容 | |:-:|---------| | 1 | `01-common.instructions.md` §意图路由表是否覆盖所有 8 个意图（dev/fix/analyze/audit/self-fix/resume/other/chat），且与 `routing/SKILL.md` / `intent/SKILL.md` 一致 | | 2 | `intent/SKILL.md` 的三问法和前置识别是否可由 LLM 无歧义执行 | | 3 | `routing/SKILL.md` 的子类型路由表是否与各工作流 Skill 声明的子类型一致 | --- ### B — 内容质量 **D4 内容完整性 🔴** | # | 检查内容 | |:-:|---------| | 1 | 每个 SKILL.md 是否有实质性内容（非空壳/非占位符）| | 2 | dev/fix/audit 工作流描述中 CP 流程是否完整（CP1/CP2/CP3 定义、触发条件、模板引用）| | 3 | `compliance/SKILL.md` 的 FC/SC/RC 三层检查项是否有完整的可执行判断标准 | | 4 | `cp-gate/SKILL.md` 是否覆盖所有 CP 响应类型（确认/修正/拒绝/追问/模糊）| **D5 跨文件一致性 🔴** | # | 检查内容 | |:-:|---------| | 1 | L1~L3 联动检查（见上方关键检查）| | 2 | `02-output-paths.instructions.md` 与各工作流 report 模板的产物路径是否一致 | | 3 | `17-compliance.instructions.md` 的 PC0~PC10 预检查、`15-memory.instructions.md` 的读取顺序与 `01-common.instructions.md` 的路由 / Profile 规则是否对齐 | **D6 示例可执行性 🟡** | # | 检查内容 | |:-:|---------| | 1 | Skills 中的示例代码块（如 `.http`/`.cjs` 格式）是否可直接执行 | | 2 | `api-verification/SKILL.md` 的双产物示例是否语法正确 | | 3 | `memory/SKILL.md` 中的路径模板变量（``/``/`YYYYMMDD`）是否有明确的替换规则 | --- ### C — 可维护性 **D7 职责边界 🔴** | # | 检查内容 | |:-:|---------| | 1 | 工作流主规则是否收敛在 `instructions/`，Skill 仅承载详细检查标准 / 模板 / 补充说明，Agent 入口不重复维护同一事实 | | 2 | `instructions/`、`skills/`、`website` 之间是否存在同一事实多处维护但无权威来源声明的分叉 | | 3 | `compliance/SKILL.md` 是否包含非合规检查内容（如执行逻辑）→ 应拆出 | **D8 版本标注 🟡** | # | 检查内容 | |:-:|---------| | 1 | `plugin.json` 的 `version` 字段是否与 `CHANGELOG.md` 最新版本一致 | | 2 | `RULES.md` 头部的版本号是否与 `plugin.json` 一致 | **D9 引用准确性 🔴** | # | 检查内容 | |:-:|---------| | 1 | 各 SKILL.md 中引用的 prompt 模板路径（`prompts/*.prompt.md`）是否全部存在 | | 2 | Agent 入口文件中的职责说明是否与 `instructions/` 当前真实执行面一致，未继续引用已下沉或已移除的主逻辑 | | 3 | `report/SKILL.md` 模板引用是否覆盖所有工作流（dev/fix/analyze/audit） | --- ### D — AI 执行性 **D10 指令明确性 🔴** | # | 检查内容 | |:-:|---------| | 1 | 每个 SKILL.md 是否有可操作的执行步骤（不止是"应该做X"，而是"执行步骤：1.X 2.Y"）| | 2 | compliance SC 层每个检查项是否有明确的判断标准（是/否，而非"合理即可"）| | 3 | fix 工作流的"修复三步必做"是否有具体的 grep 命令示例或搜索模式 | | 4 | `memory/SKILL.md` 的 SUMMARY.md 格式是否有可直接填写的表头模板 | **D11 冲突检测 🔴** | # | 检查内容 | |:-:|---------| | 1 | `00-safety.instructions.md` 与 `01-common.instructions.md` / 各工作流 instructions 之间是否存在规则冲突 | | 2 | `instructions/` 各文件之间优先级是否明确，是否有相互矛盾的约束 | | 3 | `17-compliance.instructions.md` 的预检查 / 合规顺序是否与 `01-common.instructions.md`、`15-memory.instructions.md` 的约束优先级一致 | **D12 路由正确性 🔴** | # | 检查内容 | |:-:|---------| | 1 | `intent/SKILL.md` 三问法的每个分支是否都能唯一确定一个目标工作流 | | 2 | 意图为 `other` 时是否明确路由到 plan 工作流（无兜底缺失）| | 3 | `token-check/SKILL.md` 的当前状态声明是否与 `plugin.json` tier 配置一致 | --- ### E — 可扩展性 **D13 扩展点标注 💡** | # | 检查内容 | |:-:|---------| | 1 | 新增工作流子类型时需更新的文件是否有注释标注（L1~L3 联动）| | 2 | `plugin.json` 的 `_note_skills` 字段是否说明了子类型 Skill 注册方式 | **D14 租户覆盖支持 💡** | # | 检查内容 | |:-:|---------| | 1 | `instructions/tenants/` 目录是否存在并有 README 说明覆盖规则 | | 2 | 租户 instructions 的 frontmatter 格式是否有示例 | **D15 向后兼容 💡** | # | 检查内容 | |:-:|---------| | 1 | `CHANGELOG.md` 和 `changelogs/` 中的版本映射是否完整（所有变更都有对应记录）| | 2 | 现有 `npx devcodex init` 安装的文件路径是否与 `plugin.json` 注册路径一致 | --- ### F — 维度体系 **D16 维度编号唯一 🔴** | # | 检查内容 | |:-:|---------| | 1 | D1~D25 编号在本文件内无重复 | | 2 | `audit-execution-guide/SKILL.md` 的分批表与本文件维度编号一致 | **D17 优先级标注 🔴** | # | 检查内容 | |:-:|---------| | 1 | 每个维度有明确优先级标注（🔴/🟡/💡）| | 2 | 优先级与执行优先级分批表一致（🔴 维度全在第一批，不遗漏）| **D18 AI-first 设计 🟡** | # | 检查内容 | |:-:|---------| | 1 | 所有 SKILL.md 是否面向 LLM 执行而非人类阅读设计（指令式 > 描述式）| | 2 | 条件判断是否使用明确的"如果X则Y"格式，避免模糊的"应当/建议"表述 | --- ### G — 运维 **D19 废弃说明 🟡** | # | 检查内容 | |:-:|---------| | 1 | `CHANGELOG.md` 是否记录了已删除的 8 个独立 agent 文件 | | 2 | 废弃的触发方式（`@dev`/`@fix` 等旧指令）是否有迁移说明 | **D20 变更历史 🟡** | # | 检查内容 | |:-:|---------| | 1 | `CHANGELOG.md` 格式是否符合 `02-output-paths.instructions.md` 的 CHANGELOG 维护规范 | | 2 | MAJOR/MINOR 版本是否有对应 `changelogs/releases/vX.Y.Z.md` 详情文件 | **D21 Markdown 渲染格式 🔴** | # | 检查内容 | |:-:|---------| | 1 | 表格每行是否以 `\|` 开头且以 `\|` 结尾，无多余前缀字符（如 `？`/空格/不可见字符）破坏渲染 | | 2 | 表格分隔符行（`\|:-:\|---\|`）格式是否正确，列数是否与表头一致 | | 3 | 代码块是否正确闭合（开 ` ``` ` 必有对应的闭合 ` ``` `） | | 4 | 标题前后是否有空行（Markdown 渲染要求标题前后各一空行） | | 5 | 嵌套列表缩进是否统一（2 或 4 空格，不混用 Tab） | | 6 | 表格前是否有空行（Markdown 渲染要求表格前至少一空行，段落/粗体文本直接跟表格会导致渲染失败） | --- ### H — 语义正确性 **D22 产品语义正确性 🔴** > 历史教训：ENV_MODE 行为在 11+ 文件中搞反（prod 全量合规 / dev 轻量），根因是规范原型定义错误后被忠实复制，无任何节点质疑"行为分配是否符合模式名称的常规含义"。 | # | 检查内容 | |:-:|---------| | 1 | **模式语义一致性**：dev/prod/test 等环境模式的行为分配是否符合其常规产品含义（dev=开发调试/全量检查；prod=生产稳定/最小开销）| | 2 | **角色/层级语义**：Free/Pro/Enterprise 等层级名称的权限分配是否符合层级递进含义（Free ⊂ Pro ⊂ Enterprise）| | 3 | **功能开关语义**：enable/disable、skip/enforce、required/optional 等控制标志的实际行为是否与名称语义一致 | | 4 | **跨文件语义传播**：同一模式/角色名称在所有引用处的行为描述是否语义一致（防止 A 文件说 dev=轻量、B 文件说 dev=全量）| --- ### I — 跨客户端适配（v1.9.2+） > 历史背景：v1.9.0 引入 Claude Code 适配（`devcodex init --claude`、`CLAUDE.md`、`.mcp.json`、`.claude/settings.json` hooks）后，规范分发面从单一 Copilot 扩展为多客户端，但 audit 维度长期未覆盖适配层，导致 CLAUDE.md 与 `lifecycle.cjs` 实现错位、记忆 `` 字段歧义等问题。 **D23 Claude Code 适配层 🔴** | # | 检查内容 | |:-:|---------| | 1 | `CLAUDE.md` 与 `index.js` `cmdInitClaude`/`CLAUDE_SOURCES`/`CLAUDE_SETTINGS_HOOKS` 是否描述同一现实（不出现"文档说 A、实现是 B"）| | 2 | `CLAUDE.md` 引用的 `.claude/skills/` `.claude/instructions/` 路径是否与 `index.js` 实际写入路径一致 | | 3 | `hooks/_runtime/lifecycle.cjs` 对各宿主的 Bootstrap / CP gate 工作流约束与操作风险 advisory 是否对称，且 advisory 不得投影为权限 deny | | 4 | `.mcp.json` 与 `index.js` `CLAUDE_MCP_JSON` 是否一致 | | 5 | `CLAUDE.md` 是否包含 SC/RC/T 完整索引或显式跳转（避免 Claude 用户必须额外读 17-compliance）| **D24 客户端支持矩阵 🔴** | # | 检查内容 | |:-:|---------| | 1 | `README.md` 或官网首页是否给出 Client Support Matrix（明示 Copilot/Claude Code/Cursor/Codex 各等级）| | 2 | 矩阵描述与实际分发链路（`SOURCES` vs `CLAUDE_SOURCES`）一致 | | 3 | 未支持客户端（如 Codex）是否明示"无适配"而非默认隐瞒 | **D25 记忆/报告 `` 字段 🔴** | # | 检查内容 | |:-:|---------| | 1 | `15-memory.instructions.md`、`CLAUDE.md` `02-output-paths.instructions.md` 三处的 `` 枚举值是否一致（固定集合，无散值）| | 2 | `devcodex profile init` 是否按当前宿主推断写入 `"agent"` 到 `.devcodex/profile/config.json`，且 `devcodex init` / `devcodex init --claude` 不伪造 profile config | | 3 | `.devcodex/.memory/clients//` 目录命名是否符合上述枚举 | | 4 | 报告路径 `.devcodex/reports///YYYYMMDD/` 中 `` 是否同样符合枚举 |