Skip to content

Commit 298c430

Browse files
arch-teamarch-team
authored
Merge pull request #8 from arch-team/feature/skill-optimization
feat(*): Skill 优化 + Eval 管线 + 架构治理
2 parents aa25668 + 9f4819a commit 298c430

264 files changed

Lines changed: 14407 additions & 2409 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/CLAUDE.md‎

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
4242
5. **Rules 是分发规范，不是开发规范**：`rules/devpace-rules.md` 面向 Plugin 用户，开发规范在 `.claude/rules/`
4343
6. **UX 优先**：零摩擦、渐进暴露、副产物非前置、容错恢复（设计原则见 `design.md §2`）
4444
7. **理论对齐**：新增功能或调整概念模型时，对照 `knowledge/theory.md` 确保一致性
45-
8. **规范优先，不猜测**：开发 Claude Code 组件时，必须遵循 `.claude/rules/plugin-dev-spec.md` 的规范。对不确定的 API、frontmatter 字段或机制行为，通过 `claude-code-guide` agent 或官方文档查证，禁止凭记忆猜测
45+
8. **规范优先，不猜测**：开发 Claude Code 组件时，必须遵循 `.claude/rules/plugin-spec.md` 的规范。对不确定的 API、frontmatter 字段或机制行为，通过 `claude-code-guide` agent 或官方文档查证，禁止凭记忆猜测
4646

4747
## 会话协议
4848

@@ -65,8 +65,9 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
6565
| 战略规划 | `docs/planning/roadmap.md` | 阶段、里程碑、任务定义 |
6666
| 操作跟踪 | `docs/planning/progress.md` | 当前任务状态、会话历史、变更记录 |
6767
| 运行时行为规则 | `rules/devpace-rules.md` | 插件加载后 Claude 的行为 |
68-
| 文件格式契约 | `knowledge/_schema/*.md` | state/project/CR 的字段定义 |
68+
| 文件格式契约 | `knowledge/_schema/<subdir>/*.md` | 价值链对象/运行时流程/外部集成/辅助支撑的数据格式定义（四组） |
6969
| 度量指标定义 | `knowledge/metrics.md` | 指标名称、计算方式、用途 |
70+
| Skill 评估工具 | `eval/` | eval-trigger/eval-fix/eval-regress 自动化管线 |
7071

7172
### 开发规范索引（.claude/rules/，自动加载）
7273

@@ -75,15 +76,11 @@ devpace 分为两个独立层次，**产品层不得依赖开发层**：
7576
| `project-structure.md` | 项目目录结构、文件放置规则、配置文件索引；分层架构约束见本文件"分层架构"章节 |
7677
| `common.md` | 响应语言、Git 提交规范、文档命名 |
7778
| `dev-workflow.md` | 开发会话协议、任务执行、质量检查、跨会话连续性、文档级联 |
78-
| `plugin-dev-spec.md` | Claude Code 核心组件规范（Plugin 结构、Skill 规范、常见陷阱；Agent/Hook/MCP 参考见 `references/component-reference.md`） |
79-
| `info-architecture.md` | 信息架构（devpace 适配）：IA-1 至 IA-11 索引、六层架构映射、约束分级、分发层分离规则；完整原则见 `references/ia-principles.md` |
79+
| `plugin-spec.md` | devpace Plugin 编写约定（CSO、章节顺序、分拆模式；平台 API 参考见 `references/component-reference.md`） |
80+
| `ia-principles-details.md` | 信息架构元规则：IA-1 至 IA-11 索引（高冗余原则折叠为指针）、稳定性/分类/权威/预算/分级/职责的独有规则；完整原则见 `references/ia-principles.md` |
81+
| `product-architecture.md` | 产品层组件架构：依赖矩阵、通信模式、合规检测（详细映射表见 `references/product-arch-details.md`） |
82+
| `harness-engineering.md` | Harness Engineering 开发原则：环境优先调试、规则是乘数、Agent Legibility、组件设计标准、仓库知识治理 |
8083

8184
## 质量检查
8285

83-
- plugin.json 与文件系统同步（新增/删除 Skill 后立即更新）
84-
- 每个 rules/ 和 _schema/ 文件有 §0 速查卡片
85-
- 模板文件用 `{{PLACEHOLDER}}` 标记需填充的内容
86-
- Skill 的 SKILL.md 遵循 `.claude/rules/plugin-dev-spec.md` 的 frontmatter 字段定义
87-
- Skill 分拆模式：详见 `plugin-dev-spec.md` "分拆模式"章节。参考 pace-dev 和 pace-change
88-
- **分层完整性**：产品层文件不得引用 `docs/` 或 `.claude/`（见分层架构章节）
89-
- **多处出现内容的同步维护**：修改 Skill 子命令、能力描述、信号定义或 Schema 时，查阅 `.claude/references/sync-checklists.md` 获取完整同步链路和扩展清单
86+
质量检查流程详见 `dev-workflow.md` §4。补充提醒：修改 Skill 子命令、能力描述、信号定义或 Schema 时，查阅 `.claude/references/sync-checklists.md` 获取完整同步链路。

‎.claude/references/component-reference.md‎

Lines changed: 58 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,52 @@
11
# Claude Code 组件参考
22

3-
> **职责**：Agent、Hook、MCP Server 的完整规格参考。按需加载，仅在开发/修改对应组件时使用。
3+
> **职责**：Claude Code 平台级组件 API 参考（Plugin / Skill / Agent / Hook / MCP）。按需加载。
44
>
5-
> 核心开发规范见 `.claude/rules/plugin-dev-spec.md`（始终加载）。
5+
> devpace 编写约定见 `plugin-spec.md`（始终加载）。devpace 项目级映射见 `references/product-arch-details.md`。
66
7-
**章节索引**：[Agent 定义](#agent-定义) | [Hooks](#hooks) | [MCP Server 配置](#mcp-server-配置) | [规范查证方法](#规范查证方法)
7+
**章节索引**：[Plugin 结构](#plugin-结构) | [plugin.json](#pluginjson) | [SKILL.md Frontmatter](#skillmd-frontmatter) | [Agent 定义](#agent-定义) | [Hooks](#hooks) | [MCP Server 配置](#mcp-server-配置) | [常见陷阱](#常见陷阱) | [官方 plugin-dev 工具](#官方-plugin-dev-工具推荐)
8+
9+
## Plugin 结构
10+
11+
```
12+
<plugin-name>/
13+
├── .claude-plugin/
14+
├── commands/
15+
├── agents/
16+
├── skills/
17+
├── hooks/
18+
├── rules/
19+
├── output-styles/
20+
├── settings.json
21+
└── .mcp.json
22+
```
23+
24+
## plugin.json
25+
26+
`name` 是唯一必填字段（当 manifest 存在时），同时作为 Skill 的命名空间前缀（如 `devpace:pace-init`）。
27+
28+
可选字段（均为合法）：`version`、`homepage`、`repository`（字符串）、`license`、`keywords`、`commands`、`agents`、`skills`、`hooks`、`mcpServers`、`outputStyles`、`lspServers`。其中 `commands/skills/agents/hooks/mcpServers` 用于声明**额外**路径（补充默认目录的自动发现，不替代）。所有路径必须相对且以 `./` 开头。
29+
30+
## SKILL.md Frontmatter
31+
32+
每个 Skill 是 `skills/<name>/SKILL.md`。目录名即 Skill 名称。
33+
34+
**合法 frontmatter 字段**：
35+
36+
| 字段 | 说明 |
37+
|------|------|
38+
| `name` | 显示名称（可选，省略则用目录名） |
39+
| `description` | 触发条件描述——Claude 据此判断是否自动调用 |
40+
| `argument-hint` | 自动补全时的参数提示（如 `[CR编号]`） |
41+
| `allowed-tools` | 激活时免确认的工具，逗号分隔 |
42+
| `model` | `sonnet` / `opus` / `haiku` |
43+
| `disable-model-invocation` | `true` = 仅用户可调用，Claude 不会自动调用 |
44+
| `user-invocable` | `false` = 从 `/` 菜单隐藏，仅 Claude 可调用 |
45+
| `context` | `fork` = 在子 agent 上下文中运行 |
46+
| `agent` | 当 `context: fork` 时使用的 agent 类型 |
47+
| `hooks` | 作用域为此 Skill 的 Hook 配置 |
48+
49+
**字符串替换**：Skill 内容中可使用 `$ARGUMENTS`（全部参数）、`$0`/`$1`（按位参数）、`` !`command` ``（预处理器，执行 shell 命令并替换输出）。
850

951
## Agent 定义
1052

@@ -83,7 +125,7 @@ hooks:
83125
timeout: 15
84126
```
85127
86-
Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 级做精细控制。
128+
Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill 级做精细控制。devpace 当前 Skill 级 Hook 配置见 `references/product-arch-details.md` §B。
87129

88130
### 约束执行分级
89131

@@ -114,17 +156,21 @@ Skill 级 Hook 与全局 hooks.json 互补——全局做通用检查，Skill
114156

115157
Plugin 内部引用路径时使用 `${CLAUDE_PLUGIN_ROOT}`。也可在 `plugin.json` 的 `mcpServers` 字段内联定义。
116158

117-
## 规范查证方法
118-
119-
不确定时，按优先级查证：
159+
## 常见陷阱
120160

121-
1. `Task(subagent_type="claude-code-guide", prompt="查询 [具体问题]")`——内置 agent，可访问官方文档
122-
2. 官方文档：`https://code.claude.com/docs/en/`（plugins、skills、hooks、mcp、sub-agents、agent-teams）
123-
3. `claude --debug` 查看加载日志排查问题
161+
| 问题 | 原因 | 解决 |
162+
|------|------|------|
163+
| 组件放在 `.claude-plugin/` 内 | 只有 plugin.json 和 marketplace.json 在此目录 | 移到 Plugin 根目录 |
164+
| Command frontmatter 含 `name` | Command 名由文件名决定 | 删除 `name`（SKILL.md 中合法） |
165+
| Skill 不触发 | `description` 过于模糊 | 写明具体触发关键词 |
166+
| Hook 不执行 | 脚本无执行权限或缺 shebang | `chmod +x` + `#!/bin/bash` |
167+
| Hook 事件名大小写错误 | 事件名区分大小写 | `PostToolUse` 而非 `postToolUse` |
168+
| Plugin 路径用绝对路径 | 必须相对且以 `./` 开头 | 改为相对路径 |
169+
| MCP 环境变量不展开 | 语法错误 | 使用 `${VAR}` 或 `${VAR:-default}` |
124170

125-
### 官方 plugin-dev 工具（推荐）
171+
## 官方 plugin-dev 工具（推荐）
126172

127-
Anthropic 官方 plugin-dev Plugin 提供综合开发工具。安装后可用于 devpace 开发验证：
173+
查证优先级见 `plugin-spec.md` §0。Anthropic 官方 plugin-dev Plugin 提供综合开发工具：
128174

129175
| 组件 | 用途 | 使用场景 |
130176
|------|------|---------|

‎.claude/references/ia-principles.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# 通用信息架构原则
22

33
> **职责**：Claude Code 项目信息组织的 11 项通用原则。可跨项目复用，不含特定项目结构映射。
4-
> **定位**：通用原则定义层——具体项目的适配规则由各项目的 `info-architecture.md` 负责。
5-
> **按需加载**：本文件由 `info-architecture.md` 按需引用，不自动加载到上下文。
4+
> **定位**：通用原则定义层——具体项目的适配规则由各项目的 `ia-principles-details.md` 负责。
5+
> **按需加载**：本文件由 `ia-principles-details.md` 按需引用，不自动加载到上下文。
66
77
## 11 原则
88

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

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎.claude/references/product-arch-details.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# 产品层组件架构——详细映射表
2+
3+
> 按需加载。从 `product-architecture.md` §3 引用。
4+
5+
## §0 速查
6+
7+
| 章节 | 内容 | 何时查阅 |
8+
|------|------|---------|
9+
| §A | Skill-Agent 路由矩阵 | 创建/修改 Skill 的 fork/inline/model/Hook 配置 |
10+
| §B | Hook 架构模式 | 创建/修改 Hook、理解事件映射 |
11+
| §C | Agent 协作架构 | 创建/修改 Agent、理解决策边界 |
12+
| §D | Skill→Schema 依赖矩阵 | 修改 Schema 前评估影响范围 |
13+
| §E | 信号系统三方同步 | 修改信号定义时 |
14+
15+
## §A Skill-Agent 路由矩阵
16+
17+
| Skill | Agent (fork) | model | Skill 级 Hooks |
18+
|-------|-------------|-------|----------------|
19+
| pace-dev | pace-engineer | sonnet | PreToolUse: scope-check |
20+
| pace-review | pace-engineer | opus | PreToolUse: scope-check |
21+
| pace-test | pace-engineer | sonnet | — |
22+
| pace-feedback | pace-engineer | — | — |
23+
| pace-release | pace-engineer | — | — |
24+
| pace-change | pace-pm | sonnet | — |
25+
| pace-plan | pace-pm | sonnet | — |
26+
| pace-biz | pace-pm | sonnet | PreToolUse: scope-check |
27+
| pace-retro | pace-analyst | sonnet | — |
28+
| pace-guard | pace-analyst | — | — |
29+
| pace-init | _(inline)_ | — | PreToolUse: scope-check |
30+
| pace-next | pace-analyst | haiku | — |
31+
| pace-status | pace-analyst | haiku | — |
32+
| pace-pulse | pace-analyst | haiku | — |
33+
| pace-learn | _(inline)_ | — | — |
34+
| pace-theory | _(inline)_ | — | — |
35+
| pace-role | _(inline)_ | — | — |
36+
| pace-trace | _(inline)_ | — | — |
37+
| pace-sync | _(inline)_ | — | — |
38+
39+
**路由原则**：
40+
- **fork**：需要写入 `.devpace/` 或执行复杂多步操作的 Skill——提供上下文隔离
41+
- **inline**：查询型或轻量操作的 Skill——避免子 agent 开销
42+
- **Agent 鲁棒性**：fork 不可用时静默回退到 inline（rules §13.5）
43+
44+
## §B Hook 架构模式
45+
46+
**全局 vs Skill 级 Hook**：
47+
48+
| 范围 | 配置位置 | 生效条件 |
49+
|------|---------|---------|
50+
| 全局 | `hooks/hooks.json` | 始终生效（匹配 matcher） |
51+
| Skill 级 | SKILL.md `hooks` frontmatter | 仅该 Skill 激活时生效 |
52+
53+
Skill 级 Hook 位于 `hooks/skill/` 目录，命名规范：`pace-xxx-scope-check.mjs`。
54+
55+
**事件-Hook-行为映射表**：
56+
57+
| 事件 | Hook 脚本 | 行为 | 阻断? | 异步? |
58+
|------|----------|------|-------|-------|
59+
| SessionStart | session-start.sh | 加载 devpace 上下文，检测 `.devpace/` | 否 | 否 |
60+
| PreToolUse (Write\|Edit) | pre-tool-use.mjs | 质量检查：路径合规、状态一致性 | 是 (exit 2) | 否 |
61+
| PostToolUse (Write\|Edit) | post-cr-update.mjs | CR 更新后的连锁检查 | 否 | 是 |
62+
| PostToolUse (Write\|Edit) | pulse-counter.mjs | 脉搏计数器（节奏检测） | 否 | 是 |
63+
| PostToolUse (Write\|Edit) | sync-push.mjs | 外部同步推送检查 | 否 | 是 |
64+
| PostToolUse (Write\|Edit) | post-schema-check.mjs | Schema 合规验证 | 否 | 是 |
65+
| PostToolUseFailure (Write\|Edit) | post-tool-failure.mjs | 失败恢复检查 | 否 | 否 |
66+
| UserPromptSubmit | intent-detect.mjs | 意图检测（探索/推进模式判断） | 否 | 是 |
67+
| PreCompact | pre-compact.sh | 压缩前保存 devpace 状态 | 否 | 否 |
68+
| Stop | session-stop.sh | 会话检查 | 否 | 否 |
69+
| SessionEnd | session-end.sh | 最终状态保存 | 否 | 否 |
70+
| SubagentStop | subagent-stop.mjs | 子 agent 状态检查 | 否 | 否 |
71+
72+
**Skill 级 Hook 映射**：
73+
74+
| Skill | 事件 | Hook 脚本 | 用途 |
75+
|-------|------|----------|------|
76+
| pace-dev | PreToolUse (Write\|Edit) | skill/pace-dev-scope-check.mjs | 开发范围守护 |
77+
| pace-review | PreToolUse (Write\|Edit) | skill/pace-review-scope-check.mjs | 审核范围守护 |
78+
| pace-init | PreToolUse (Write\|Edit) | skill/pace-init-scope-check.mjs | 初始化范围守护 |
79+
| pace-biz | PreToolUse (Write\|Edit) | skill/pace-biz-scope-check.mjs | 业务分析范围守护 |
80+
81+
**Hook 通信协议**：
82+
83+
```
84+
事件触发 → stdin JSON（含 tool_name, file_path 等上下文）
85+
→ Hook 脚本解析 JSON + 读取 .devpace/ 状态文件
86+
→ exit 0（放行）| exit 2（阻断 + stderr 提示）| 其他（非阻断错误）
87+
→ stdout 反馈信息注入会话上下文
88+
```
89+
90+
**关键约束**：Hook 脚本不解析 `rules/`、`skills/`、`knowledge/` 中的 Markdown 文件——所有状态感知通过 `.devpace/` 运行时文件和 stdin JSON 完成。
91+
92+
## §C Agent 协作架构
93+
94+
**三角色模型**：
95+
96+
| Agent | 职责域 | 核心能力 | 工具权限 |
97+
|-------|--------|---------|---------|
98+
| pace-engineer | 工程执行 | CR 实现、质量门、代码变更 | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion |
99+
| pace-pm | 产品规划 | 迭代规划、变更管理、业务对齐 | Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion |
100+
| pace-analyst | 度量分析 | 指标收集、回顾分析、趋势报告 | Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion |
101+
102+
**决策边界矩阵**：
103+
104+
| 决策类型 | 决策者 | Agent 角色 |
105+
|---------|--------|-----------|
106+
| 代码实现方案 | pace-engineer | 执行 + 建议 |
107+
| CR 状态转换 | pace-engineer | 执行（受 Gate 约束） |
108+
| 迭代范围调整 | pace-pm | 建议（需用户确认） |
109+
| 需求变更评估 | pace-pm | 分析 + 建议 |
110+
| 度量报告生成 | pace-analyst | 执行 |
111+
| 风险预警 | pace-analyst | 分析 + 提示 |
112+
| Gate 3 审批 | **人类** | 不可代替（IR-2） |
113+
114+
**Memory 策略**：Agent 使用 `memory: project`（`.claude/agent-memory/<name>/`）持久化跨会话上下文。下次 fork 到同一 Agent 时自动加载。适用于：迭代上下文延续（pace-pm）、技术决策记忆（pace-engineer）、度量基线记忆（pace-analyst）。
115+
116+
## §D Skill→Schema 依赖矩阵
117+
118+
基于产品层文件的直接路径引用统计。`>` = 直接引用。权威 fan-in 数据见 `knowledge/_schema/README.md`。
119+
120+
| Skill | cr-format | project-format | checks-format | iteration-format | test-strategy | insights-format | 其他 Schema |
121+
|-------|-----------|---------------|---------------|-----------------|--------------|----------------|-------------|
122+
| pace-init | | > | > | | | | context-format, integrations-format |
123+
| pace-dev | > | | | | > | | br-format, pf-format, risk-format, context-format |
124+
| pace-review | > | | | | | | accept-report-contract |
125+
| pace-test | > | | | | > | | test-baseline-format |
126+
| pace-change | > | | | > | | | |
127+
| pace-plan | | | | > | | | |
128+
| pace-biz | | > | | | | | epic-format, opportunity-format, readiness-score, merge-strategy |
129+
| pace-retro | | | | | | > | test-baseline-format |
130+
| pace-guard | | | | | | | risk-format |
131+
| pace-feedback | > | | | | | | |
132+
| pace-release | | | | | | | release-format, integrations-format |
133+
| pace-learn | | | | | | > | |
134+
| pace-sync | | | | | | | sync-mapping-format |
135+
| pace-trace | | | | | | | adr-format |
136+
| pace-pulse | > | | | | | | |
137+
| rules | > | | > | > | | | state-format |
138+
139+
### Schema Fan-in 摘要
140+
141+
| Schema 文件 | Fan-in | 稳定性要求 |
142+
|------------|--------|-----------|
143+
| cr-format.md | 10 | 极高——变更需评估 5+ Skill 影响 |
144+
| checks-format.md | 7 | 高——变更需评估 5+ Skill 影响 |
145+
| iteration-format.md | 4 | 高 |
146+
| insights-format.md | 4 | 高 |
147+
| sync-mapping-format.md | 4 | 高 |
148+
| integrations-format.md | 3 | 中 |
149+
| test-baseline-format.md | 3 | 中 |
150+
151+
## §E 信号系统三方同步
152+
153+
信号（Signal）驱动 Skill 间的衔接推荐：
154+
155+
```
156+
signal-priority.md (SSOT) ← 定义信号优先级
157+
signal-collection.md ← 定义信号采集规则
158+
↓
159+
pace-next / pace-pulse / pace-status ← 消费信号，生成推荐
160+
↓
161+
session-start.sh (推送) → pace-next (拉取，去重) ← 会话级信号流
162+
```
163+
164+
三方同步要求：变更信号定义时，`signal-priority.md`、`signal-collection.md`、消费 Skill（next/pulse/status）三者需同步更新。详见 `references/sync-checklists.md`。

0 commit comments

Comments
 (0)