feat: 工程质量深度优化 + eval 自动化 + IA 信息架构体系

.claude/CLAUDE.md

@@ -72,43 +72,18 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
 
 | 规范文件 | 职责 |
 |---------|------|
+| `project-structure.md` | 项目目录结构、文件放置规则、配置文件索引；分层架构约束见本文件"分层架构"章节 |
 | `common.md` | 响应语言、Git 提交规范、文档命名 |
 | `dev-workflow.md` | 开发会话协议、任务执行、质量检查、跨会话连续性、文档级联 |
-| `plugin-dev-spec.md` | Claude Code 组件开发规范（Plugin 结构、Skill/Agent/Hook/MCP 规范、常见陷阱） |
+| `plugin-dev-spec.md` | Claude Code 核心组件规范（Plugin 结构、Skill 规范、常见陷阱；Agent/Hook/MCP 参考见 `references/component-reference.md`） |
+| `info-architecture.md` | 信息架构（devpace 适配）：IA-1 至 IA-11 索引、六层架构映射、约束分级、分发层分离规则；完整原则见 `references/ia-principles.md` |
 
 ## 质量检查
 
 - plugin.json 与文件系统同步（新增/删除 Skill 后立即更新）
 - 每个 rules/ 和 _schema/ 文件有 §0 速查卡片
 - 模板文件用 `{{PLACEHOLDER}}` 标记需填充的内容
 - Skill 的 SKILL.md 遵循 `.claude/rules/plugin-dev-spec.md` 的 frontmatter 字段定义
-- Skill 分拆模式：SKILL.md 放输入/输出/高层步骤（"做什么"），当详细规则超过 ~50 行时拆出 `*-procedures.md`（"怎么做"）。参考 pace-dev 和 pace-change
+- Skill 分拆模式：详见 `plugin-dev-spec.md` "分拆模式"章节。参考 pace-dev 和 pace-change
 - **分层完整性**：产品层文件不得引用 `docs/` 或 `.claude/`（见分层架构章节）
-- **多处出现内容的同步维护**：以下信息在多个文件中出现，修改时须全部同步（箭头表示权威方向：源→派生）：
-  - accept 能力描述：`skills/pace-test/SKILL.md`（权威）→ `rules/devpace-rules.md §15`（教学派生）→ `docs/user-guide.md`（文档派生）
-  - 子命令列表：各 `SKILL.md`（权威）→ `devpace-rules.md §0`（目录索引）→ `user-guide.md`（文档派生）→ `test-procedures.md 职责行`（测试派生）
-  - 推荐使用流程：`SKILL.md`（权威）→ `user-guide.md`（文档派生）
-  - 特性文档同步：各 `SKILL.md`（权威）→ `docs/features/<skill-name>.md`（文档派生）→ `docs/features/<skill-name>_zh.md`（翻译派生）
-  - pace-next 信号摘要：`knowledge/signal-priority.md` + `knowledge/signal-collection.md`（权威）→ `skills/pace-next/SKILL.md` Step 2/3（内联摘要派生）→ `skills/pace-next/next-procedures-output-default.md`（命令引导派生）→ `docs/features/pace-next.md` + `pace-next_zh.md`（信号概览和示例派生）
-  - Schema→脚本规则同步：`knowledge/_schema/*.md`（权威）→ `scripts/validate-schema.mjs` RULES 注册表（派生）→ `scripts/collect-signals.mjs` 信号条件（派生）→ `scripts/compute-metrics.mjs` 指标公式（派生）
-- **pace-role 角色扩展清单**：新增角色时须同步以下文件（按顺序）：
-  1. `skills/pace-role/role-procedures-dimensions.md`：角色定义表
-  2. `skills/pace-role/role-procedures-switch.md`：别名映射
-  3. `skills/pace-role/role-procedures-inference.md`：关键词映射
-  4. `skills/pace-role/role-procedures-compare.md`：输出格式加一行
-  5. `skills/pace-status/status-procedures-roles.md`：完整角色模板
-  6. `skills/pace-retro/retro-procedures.md`：角色适配表
-  7. `skills/pace-change/change-procedures-impact.md`：措辞模板表
-  8. `skills/pace-pulse/SKILL.md`：角色感知表
-  9. `skills/pace-theory/theory-procedures-default.md`：角色适配输出框架
-  10. `skills/pace-next/next-procedures.md`：视角调整表
-  11. `skills/pace-release/release-procedures-notes.md`：角色视角 Release Notes
-  12. `knowledge/_schema/project-format.md`：preferred-role 枚举
-  13. `docs/features/pace-role.md` + `pace-role_zh.md`：特性文档
-- **pace-plan 子命令扩展清单**：添加新子命令时须同步以下文件（按顺序）：
-  1. 新建 `skills/pace-plan/<cmd>-procedures.md`
-  2. `skills/pace-plan/SKILL.md`：路由表 + 输入 + argument-hint
-  3. `knowledge/_schema/iteration-format.md`：写入规则（如新子命令写入迭代文件）
-  4. `rules/devpace-rules.md §11`：迭代节奏信号（如新子命令产生信号）
-  5. `docs/features/pace-plan.md` + `pace-plan_zh.md`：核心特性摘要 + 相关资源链接
-  6. `docs/user-guide.md` + `user-guide_zh.md`：参数表 + 功能描述
+- **多处出现内容的同步维护**：修改 Skill 子命令、能力描述、信号定义或 Schema 时，查阅 `.claude/references/sync-checklists.md` 获取完整同步链路和扩展清单

.claude/references/cascade-procedures.md

@@ -0,0 +1,123 @@
+# 文档级联处理步骤
+
+> **按需加载**：仅当 `dev-workflow.md` §1 上游变更检测有输出时加载本文件。日常使用见 `dev-workflow.md` §0 级联速查表。
+
+## §8.1 权威链定义
+
+```
+vision.md (WHY) → design.md (HOW) → requirements.md (WHAT) → roadmap.md (WHEN)
+```
+
+变更只能沿此方向级联（上游 → 下游），不可反向。
+
+**多文件同时变更**：当多个上游文件在同一时段被修改时，按权威链从上游到下游依次处理：先 vision.md → 再 design.md → 最后 requirements.md。上游文件的级联结果可能覆盖下游文件的独立变更，因此必须按此顺序，避免重复或矛盾的级联更新。
+
+## §8.2 场景 A：vision.md 变更
+
+**触发**：OBJ 增删改、北极星调整、护城河策略变化。
+
+**影响分析**：
+
+1. 识别受影响的 OBJ → 通过 roadmap.md "对应 OBJ" 定位受影响的 Phase
+2. 检查 design.md 哪些章节基于该 OBJ 设计（参考 design.md §1 设计优先级）
+3. 检查 requirements.md 哪些 S/F 条目源自该 OBJ
+4. 评估 progress.md 当前任务是否受影响
+
+**动作**：更新受影响的下游文档，或标记 `<!-- REVIEW: vision.md [OBJ-X] changed [date] -->`。
+
+## §8.3 场景 B：design.md 变更
+
+**触发**：UX 原则变化、状态机修改、工作流重设计、新增/删除章节。
+
+**影响分析**：
+
+1. 通过 design.md Skill 映射（§12）定位受影响的 Skill
+2. 检查 requirements.md 哪些 S/F/NF 条目基于变更的设计章节
+3. 检查已实现的 Skill 是否需要适配
+4. 评估 progress.md 是否需要新增任务
+
+**动作**：更新 requirements.md 受影响条目 + 必要时在 progress.md 新增任务。
+
+## §8.4 场景 C：requirements.md 变更
+
+**触发**：新增场景、验收标准修改、功能需求变更、优先级调整。
+
+**影响分析**：
+
+1. 识别受影响的 S/F/NF 条目 → 定位 progress.md 对应的任务
+2. 检查已实现的 Skill 是否需要返工
+3. 评估是否需要在 progress.md 新增任务
+
+**动作**：更新 progress.md 任务列表 + 必要时调整 roadmap.md 里程碑。
+
+## §8.5 场景 D：自触发级联（Claude 修改上游文档）
+
+**触发**：当前任务本身要求修改 vision.md / design.md / requirements.md。由 §3 第 5 条或反向反馈触发。
+
+**与场景 A/B/C 的区别**：
+- 不需要"提示用户建议评估"——Claude 自己就是修改者，直接评估
+- 变更内容已知——不需要 diff，直接从修改内容出发分析影响
+
+**处理步骤**：
+
+1. 完成上游文档修改并 git commit
+2. 明确记录本次修改了什么（哪个文档、哪些章节、变更性质）
+3. 根据修改的文档级别，按场景 A/B/C 对应的影响分析维度，评估对下游的影响
+4. 检查 progress.md "当前任务"表中其他"进行中"或"待做"任务是否受影响
+   - 受影响的任务：在"说明"列添加备注 `[design.md §X 已更新，需适配]`
+   - 需要新增任务：立即添加到 progress.md（遵循 §5 关联条目填写要求）
+5. 在 progress.md "变更记录"添加条目，原因列标注"自触发：任务 [任务名]"
+
+## §8.6 场景 E：roadmap.md 变更
+
+**触发**：里程碑增删改、Phase 调整、验证计划变更。
+
+**影响分析**：
+
+1. 识别受影响的里程碑 → 检查 progress.md 对应任务
+2. 评估任务定义是否需要调整（关联条目、里程碑归属）
+
+**动作**：更新 progress.md 任务列表。roadmap.md 是权威链终点，不再向下级联。
+
+## §8.7 级联执行清单（通用）
+
+1. 识别变更范围（哪个文档、哪个章节/条目）
+2. 沿权威链向下追踪影响
+3. 对每个受影响的下游文档：读取、评估、更新或标记待审
+4. 在 progress.md "变更记录"添加条目：`| 日期 | 变更描述 | 原因 |`
+5. 若有进行中的任务受影响，在 progress.md "当前任务"的"说明"列添加备注
+6. 若变更涉及 `.claude/` 文件，评估 `rules/` 下其他文件是否受影响
+
+## §8.8 陈旧标记
+
+使用 HTML 注释标记在下游文档的受影响位置：
+
+```
+<!-- REVIEW: [source] changed [date], may affect this section -->
+```
+
+解决后移除标记。
+
+## §8.9 变更决策记录
+
+所有级联处理的结果记入 progress.md "变更记录"表。
+
+格式：`| 日期 | [源文档] 变更：[内容] → [下游影响] | [原因] |`
+
+## §8.10 反向反馈流程
+
+> 由 `dev-workflow.md` §3 触发：实现中发现上游文档有歧义、缺失或不可行之处。
+
+**触发条件**（满足任一）：
+- design.md 的设计规格不可行或有矛盾
+- requirements.md 的验收标准存在歧义或无法满足
+- vision.md 的 OBJ/MoS 定义与实际不匹配
+
+**处理步骤**：
+1. 暂停当前实现，向用户描述问题和建议修正方案
+2. 获得用户确认后，修改上游文档并 git commit
+3. 执行 §8.5（自触发级联），评估修正对其他任务的影响
+4. 在 progress.md "变更记录"添加条目，原因列标注"反向反馈：实现 [任务名] 时发现 [问题简述]"
+5. 继续当前任务（基于修正后的上游文档）
+
+**原则**：反向反馈不是"反向级联"，而是"修正上游 → 正向级联"的闭环。下游实现永远不能直接改变上游设计意图，只能报告→确认→修正→正向级联。

.claude/references/component-reference.md

@@ -0,0 +1,136 @@
+# Claude Code 组件参考
+
+> **职责**：Agent、Hook、MCP Server 的完整规格参考。按需加载，仅在开发/修改对应组件时使用。
+>
+> 核心开发规范见 `.claude/rules/plugin-dev-spec.md`（始终加载）。
+
+**章节索引**：[Agent 定义](#agent-定义) | [Hooks](#hooks) | [MCP Server 配置](#mcp-server-配置) | [规范查证方法](#规范查证方法)
+
+## Agent 定义
+
+Agent 文件放在 `agents/` 目录，frontmatter 必须包含 `name` 和 `description`。
+
+**合法 frontmatter 字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `name` | **必填**，Agent 名称 |
+| `description` | **必填**，Agent 描述 |
+| `tools` | 允许的工具列表 |
+| `disallowedTools` | 禁止的工具列表 |
+| `model` | `sonnet` / `opus` / `haiku` |
+| `color` | UI 背景色（`blue`/`cyan`/`green`/`yellow`/`red`/`magenta`） |
+| `permissionMode` | 权限模式 |
+| `maxTurns` | 最大轮次 |
+| `skills` | 可用 Skill 列表 |
+| `mcpServers` | 可用 MCP Server |
+| `memory` | 记忆持久化级别（见下方备注） |
+| `hooks` | Agent 级 Hook 配置 |
+| `isolation` | `worktree` = 独立 git worktree 运行 |
+
+`memory` 持久化路径：`user` → `~/.claude/agent-memory/<name>/`，`project` → `.claude/agent-memory/<name>/`，`local` → 仅当前会话。下次 fork 时自动加载。`isolation: worktree` 时无变更自动清理。
+
+通过 Task 工具调用：`Task(subagent_type="agent-name", prompt="...", description="...")`。子 agent 不能再嵌套调用 Task。
+
+## Hooks
+
+Hook 事件名称区分大小写。可用事件：
+
+| 事件 | 触发时机 | 可阻断? |
+|------|---------|---------|
+| `PreToolUse` | 工具执行前 | 是（exit 2） |
+| `PostToolUse` | 工具执行成功后 | 否 |
+| `PostToolUseFailure` | 工具执行失败后 | 否 |
+| `UserPromptSubmit` | 用户提交 prompt | 是 |
+| `PreCompact` | 上下文压缩前（manual/auto） | 否 |
+| `Stop` | Claude 完成响应 | 是 |
+| `SessionStart` / `SessionEnd` | 会话开始/结束 | 否 |
+| `SubagentStart` / `SubagentStop` | 子 agent 启停 | 部分 |
+| `TeammateIdle` / `TaskCompleted` | 团队协作事件 | 是（exit 2） |
+
+配置位置（优先级从高到低）：
+
+1. managed settings
+2. `.claude/settings.json`（项目共享）
+3. `.claude/settings.local.json`（项目本地）
+4. `~/.claude/settings.json`（全局）
+5. Plugin `hooks/hooks.json`
+
+Hook 脚本中使用 `${CLAUDE_PLUGIN_ROOT}` 引用 Plugin 根目录。exit 0 = 成功，exit 2 = 阻断，其他 = 非阻断错误。
+
+### Hook 类型
+
+| 类型 | 说明 | 超时默认 |
+|------|------|---------|
+| `command` | 执行 shell 命令，通过 stdin 接收 JSON 输入 | 无默认 |
+| `prompt` | LLM 评估 prompt 内容，决定是否放行 | 30s |
+| `agent` | LLM agent 执行（有工具访问权限），决定是否放行 | 60s |
+
+`command` 类型额外支持 `"async": true`（后台执行，不阻塞主流程）。`prompt`/`agent` 类型具有语义理解能力，适合替代简单的正则匹配做复杂判断。
+
+### Skill 级 Hooks
+
+SKILL.md 的 `hooks` frontmatter 字段支持定义仅在该 Skill 激活时生效的 Hook：
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher:
+        tool_name: "Write|Edit"
+      hooks:
+        - type: prompt
+          prompt: "验证此写入是否合法..."
+          timeout: 15
+```
+
+Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 级做精细控制。
+
+### 约束执行分级
+
+选择约束的执行保障级别时参考：
+
+| 可靠性 | 机制 | 适用场景 |
+|--------|------|---------|
+| 最高 | Hook command + exit 2 | 不可逆操作阻断、模式保护 |
+| 高 | Hook prompt/agent | 需语义理解的检查 |
+| 中 | Skill 指令 + 铁律标记 | 工作流约束 |
+| 基线 | Rules 文本建议 | 行为规范、风格指引 |
+
+## MCP Server 配置
+
+项目级配置放在根目录 `.mcp.json`，格式：
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "path/to/server",
+      "args": ["--flag"],
+      "env": { "KEY": "${ENV_VAR}", "KEY2": "${VAR:-default}" }
+    }
+  }
+}
+```
+
+Plugin 内部引用路径时使用 `${CLAUDE_PLUGIN_ROOT}`。也可在 `plugin.json` 的 `mcpServers` 字段内联定义。
+
+## 规范查证方法
+
+不确定时，按优先级查证：
+
+1. `Task(subagent_type="claude-code-guide", prompt="查询 [具体问题]")`——内置 agent，可访问官方文档
+2. 官方文档：`https://code.claude.com/docs/en/`（plugins、skills、hooks、mcp、sub-agents、agent-teams）
+3. `claude --debug` 查看加载日志排查问题
+
+### 官方 plugin-dev 工具（推荐）
+
+Anthropic 官方 plugin-dev Plugin 提供综合开发工具。安装后可用于 devpace 开发验证：
+
+| 组件 | 用途 | 使用场景 |
+|------|------|---------|
+| **plugin-validator** Agent | 10 步综合验证（Manifest/目录/Skills/Hooks/安全） | 任何 Plugin 结构变更后 |
+| **skill-reviewer** Agent | Skill 质量审查（description/内容/渐进披露） | Skill 新增或修改后 |
+| **agent-creator** Agent | AI 辅助 Agent 创建 | 新增 Agent 定义时 |
+| `/plugin validate` | 内置命令，验证 plugin.json 基本结构 | 快速检查 |
+
+安装：`/plugin install plugin-dev@claude-plugins-official`

.claude/references/ia-principles.md

@@ -0,0 +1,29 @@
+# 通用信息架构原则
+
+> **职责**：Claude Code 项目信息组织的 11 项通用原则。可跨项目复用，不含特定项目结构映射。
+> **定位**：通用原则定义层——具体项目的适配规则由各项目的 `info-architecture.md` 负责。
+> **按需加载**：本文件由 `info-architecture.md` 按需引用，不自动加载到上下文。
+
+## 11 原则
+
+| # | 原则 | 核心要求 | 应用指南 |
+|---|------|---------|---------|
+| IA-1 | 单向依赖 | 信息从抽象流向具体，不可反向 | 上层定义概念，下层实现细节；下层只引用同层或上层 |
+| IA-2 | 抽象分层 | 不同抽象层级放在不同文件 | 路由（做什么）与步骤（怎么做）分文件；Manifest 与组件分离 |
+| IA-3 | 稳定-易变分离 | 高扇入文件隔离易变内容以保持稳定 | 被多处引用的文件保持低变更频率；易变部分拆出独立文件 |
+| IA-4 | 信息分类 | 不同信息类型不混放 | 步骤、约束、概念、结构、路由、实例各归其位 |
+| IA-5 | 按需加载 | 只加载当前上下文所需的最小信息集 | description 仅提供触发信息；复杂内容分级延迟加载 |
+| IA-6 | 单一权威 | 每条信息有且仅有一个权威定义点 | 派生文件注明来源；变更沿源→派生方向传播 |
+| IA-7 | 确定性分级 | 约束的执行保障级别匹配其关键程度 | 铁律用 Hook 保障；推荐用文本声明；按关键度选机制 |
+| IA-8 | 可发现性优先 | 入口信息为发现而设计，不为完整而设计 | description 写触发条件（When），不写行为描述（What） |
+| IA-9 | 认知清晰 | 面向 LLM 的指令精确无歧义，阻止合理化绕过 | 铁律配反合理化清单；模糊表述用具体关键词替代 |
+| IA-10 | 契约隔离 | 数据格式由独立契约层约束 | 共享数据定义独立 Schema；生产方和消费方都依赖契约 |
+| IA-11 | 单一职责 | 每个文件只有一个核心职责 | 多个独立变更原因 = 需要分拆；越界内容压缩为引用 |
+
+## 约束分级标记
+
+| 标记 | 含义 | 执行保障 |
+|------|------|---------|
+| `iron rule` | 铁律，不可违反 | 应有 Hook 或自动化测试 |
+| `required` | 必须遵循 | 代码审查检查 |
+| `recommended` | 推荐实践 | 最佳实践指引 |

.claude/references/plugin-info-layers.md

@@ -0,0 +1,27 @@
+# devpace 信息分层架构
+
+> **职责**：devpace Plugin 的六层信息架构和资产类型定义。
+
+## 六层架构
+
+```
+Layer 6: knowledge/theory     (Why  — 概念知识，被动加载，极少变更)
+Layer 5: rules/               (Must — 行为约束，会话启动时自动加载)
+Layer 4: knowledge/_schema/   (Shape — 数据格式契约，按需加载)
+Layer 3: skills/*/SKILL.md    (What — 路由层，description 触发加载)
+Layer 2: skills/*/*-procedures.md (How — 操作步骤，按状态/子命令条件加载)
+Layer 1: knowledge/_templates/ (Instance — 具体实例，实例化时加载)
+```
+
+依赖方向：**仅允许下层引用上层**。Layer 2 引用 Layer 4 的格式定义；Layer 4 不引用 Layer 2 的实现细节。
+
+## 信息类型 → 资产映射
+
+| 信息类型 | Plugin 资产 | 特征 |
+|---------|------------|------|
+| 步骤（Procedure） | `*-procedures.md` | 按步操作指令 |
+| 约束（Principle） | `rules/*.md` | 行为规范 |
+| 概念（Concept） | `knowledge/*.md` | 背景知识 |
+| 结构（Structure） | `knowledge/_schema/*.md` | 数据格式定义 |
+| 路由（Process） | `SKILL.md` | 工作流分发 |
+| 实例（Fact） | `knowledge/_templates/*.md` | 具体模板 |

.claude/references/skill-content-check.md

@@ -0,0 +1,15 @@
+# Skill 内容质量验证方法
+
+> **按需加载**：仅在 Skill 开发/修改时参考。推荐方法，非强制流程。
+
+## RED-GREEN-REFACTOR 验证法
+
+1. **基线观测（RED）**：禁用目标 Skill → 观察 Claude 的默认行为 → 记录与期望行为的具体偏差
+   - 记录格式："无 Skill 时 Claude 做了 [X]，期望行为是 [Y]"
+   - 至少用 2 个不同复杂度的场景观测
+2. **最小规则（GREEN）**：针对观测到的偏差写最小修正规则 → 启用 Skill → 确认偏差被修正
+   - 原则：一条规则修正一个偏差，不做预防性规则
+3. **漏洞补充（REFACTOR）**：用不同复杂度场景（S/M/L）压力测试 → 发现新偏差 → 补充合理化预防表
+   - 重点关注：Claude 在长会话或复杂任务中是否"合理化"跳过规则
+
+**适用场景**：新 Skill 开发、Skill 规则重大修改、发现 Skill 行为偏差时。