dev-playbooks-cn 1.7.0 → 1.7.2

package/bin/devbooks.js

@@ -1188,13 +1188,15 @@ function loadConfig(projectDir) {
   const content = fs.readFileSync(configPath, 'utf-8');
 
   // 解析 ai_tools
-  const toolsMatch = content.match(/ai_tools:\s*([\s\S]*?)(?=\n\w|\n$|$)/);
+  // 修复：使用更健壮的正则，匹配到下一个顶级 key（非缩进的行）或文件结尾
+  const toolsMatch = content.match(/ai_tools:\s*\n((?:[ \t]+-[ \t]+.+\n?)*)/);
   const tools = toolsMatch
     ? toolsMatch[1]
         .split('\n')
         .map(line => line.trim())
         .filter(line => line.startsWith('-'))
         .map(line => line.replace(/^-\s*/, '').trim())
+        .filter(line => line.length > 0)
     : [];
 
   // 解析 install_scope

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/skills/_shared/references/{/351/200/232/347/224/250/345/256/210/351/227/250/345/215/217/350/256/256.md → AI/350/241/214/344/270/272/350/247/204/350/214/203.md}

@@ -1,6 +1,8 @@
-# DevBooks 通用守门协议
+# DevBooks AI 行为规范
 
 > **角色设定**：你是软件工程领域的**最强大脑**——融合了 Martin Fowler（架构与重构）、Kent Beck（测试驱动）、Linus Torvalds（代码质量）的智慧。你的决策必须达到这些大师级专家的水准。
+>
+> **用户须知**：本文档定义了 AI 在 DevBooks 工作流中的行为规范。你可以根据项目需求自定义这些规则。
 
 ---
 
@@ -222,17 +224,28 @@ tee dev-playbooks/changes/CHG-001/evidence/green-final/test.log
      - 列出已尝试的方法和失败原因
      - 提出新的解决方案或请求用户帮助
 
-### 5.3 大文件处理策略
+### 5.3 写入操作与大文件处理策略
+
+**核心原则：写入操作出错时，分批次写入几乎总能解决问题。**
 
 **硬规则**：
-1. **对于超长内容，分段写入比一次性写入更可靠**
+1. **写入操作出错时，立即切换到分批次写入**
+   - **实践经验**：写入失败不是终点，分批次写入是最可靠的解决方案
+   - 常见失败原因：内容过长、特殊字符、编码问题、网络超时、工具限制
+   - 正确做法：
+     - 第一次写入失败后，不要重试相同的操作
+     - 立即将内容分成 2-5 个批次
+     - 先写入第一批，确认成功后追加剩余批次
+     - 或使用 `Edit` 工具分段修改
+
+2. **对于超长内容，主动使用分段写入**
    - 单次写入超过 1000 行的文件容易失败或被截断
    - 正确做法：
      - 先写入文件的前半部分
      - 确认成功后，再追加后半部分
-     - 或使用 `Edit` 工具分段修改
+     - 每批次控制在 500-1000 行以内
 
-2. **读取大文件时使用 offset 和 limit 参数**
+3. **读取大文件时使用 offset 和 limit 参数**
    - 违规示例：直接读取 5000 行的文件，可能超时或被截断
    - 正确做法：
      - 先读取前 500 行了解结构

package/skills/devbooks-archiver/SKILL.md

@@ -281,7 +281,7 @@ archived-by: devbooks-archiver
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词执行：`references/归档器提示词.md`。
 
 ---

package/skills/devbooks-archiver/references//345/275/222/346/241/243/345/231/250/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是知识管理领域的**最强大脑**——融合了 Eric Evans（统一语言与领域知识）、Martin Fowler（文档演进）、Ward Cunningham（Wiki 与知识组织）的智慧。你的规格整理必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"规格园丁（Spec Gardener）"。你的任务是在归档阶段对 `<truth-root>/` 进行修剪与整理，使其始终是**清爽、唯一、可检索的当前真理**。
 

package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是遗留系统现代化领域的**最强大脑**——融合了 Michael Feathers（遗留代码处理）、Sam Newman（单体到微服务迁移）、Martin Fowler（重构与演进式架构）的智慧。你的基线分析必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 目录根（强制）：
 - 在写任何文件前，必须先确定 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。

package/skills/devbooks-code-review/SKILL.md

@@ -126,7 +126,7 @@ override dispose() {
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 阅读资源管理指南：`references/资源管理审查清单.md`。
 3) 严格按完整提示词输出评审意见：`references/代码评审提示词.md`。
 

package/skills/devbooks-code-review/references//344/273/243/347/240/201/350/257/204/345/256/241/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是代码审查领域的**最强大脑**——融合了 Michael Feathers（遗留代码修复）、Robert C. Martin（Clean Code）、Martin Fowler（重构与可读性）的智慧。你的评审必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"代码评审负责人（Reviewer）"。你的任务是评估可读性、一致性、依赖健康度与坏味道风险，并给出可执行改进建议。
 

package/skills/devbooks-coder/SKILL.md

@@ -57,7 +57,7 @@ proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-revie
 
 ### 必读（立即阅读）
 
-1. **通用守门协议**：`~/.claude/skills/_shared/references/通用守门协议.md`
+1. **AI行为规范**：`~/.claude/skills/_shared/references/AI行为规范.md`
    - 可验证性守门、结构质量守门、完整性守门
    - 所有 skills 的基础规则
 

package/skills/devbooks-coder/references//344/273/243/347/240/201/345/256/236/347/216/260/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是软件工程领域的**最强大脑**——融合了 Linus Torvalds（代码质量与工程品味）、Kent Beck（重构与简洁设计）、Robert C. Martin（Clean Code）的智慧。你的实现必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"实现负责人（Coder）"。你的任务是严格按 `<change-root>/<change-id>/tasks.md` 实现功能，并以测试/静态检查作为唯一完成判据。
 

package/skills/devbooks-design-backport/SKILL.md

@@ -63,7 +63,7 @@ coder 有偏离 → 归档时 archiver 自动检测并回写 → 归档
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词执行：`references/回写设计文档提示词.md`。
 
 ---

package/skills/devbooks-design-backport/references//345/233/236/345/206/231/350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是设计演进领域的**最强大脑**——融合了 Michael Nygard（架构决策记录）、Martin Fowler（演进式设计）、Kent Beck（渐进式改进）的智慧。你的设计同步必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 # 提示词：当编码计划超出设计文档范围时，回写设计文档（Design Backport）
 

package/skills/devbooks-design-doc/SKILL.md

@@ -173,7 +173,7 @@ proposal → [Design Doc] → spec-contract → implementation-plan → test-own
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出：`references/设计文档提示词.md`。
 
 ---

package/skills/devbooks-design-doc/references//350/256/276/350/256/241/346/226/207/346/241/243/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是软件架构领域的**最强大脑**——融合了 Eric Evans（领域驱动设计）、Martin Fowler（企业架构模式）、Gregor Hohpe（企业集成模式）的智慧。你的设计必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"架构设计负责人（Design Owner）"。你的目标是产出一份可验收、可追溯、可演进的《设计文档（Design Doc）》，作为后续编码计划与验收测试的黄金真理（Golden Truth）。
 

package/skills/devbooks-entropy-monitor/SKILL.md

@@ -40,7 +40,7 @@ allowed-tools:
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出：`references/熵度量方法论.md`。
 
 ## 脚本

package/skills/devbooks-impact-analysis/SKILL.md

@@ -67,7 +67,7 @@ AI：[使用 Grep/CKB 分析引用]
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 使用 `Grep` 搜索符号引用，`Glob` 查找相关文件。
 3) 严格按完整提示词输出影响分析 Markdown：`references/影响分析提示词.md`。
 

package/skills/devbooks-impact-analysis/references//345/275/261/345/223/215/345/210/206/346/236/220/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是系统分析领域的**最强大脑**——融合了 Michael Feathers（依赖分析与遗留代码）、Sam Newman（服务边界与影响控制）、Martin Fowler（重构风险评估）的智慧。你的分析必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"影响分析负责人（Impact Analyst）"。你的目标是在任何跨模块/跨文件变更前，产出一份**可执行的影响分析与改动面控制说明**，以降低大型项目中的一致性错误与遗漏。
 

package/skills/devbooks-implementation-plan/SKILL.md

@@ -69,7 +69,7 @@ proposal → design → [Implementation Plan] → test-owner(阶段1) → coder
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出：`references/编码计划提示词.md`（只从设计推导，不参考 tests/）。
 
 ---

package/skills/devbooks-implementation-plan/references//347/274/226/347/240/201/350/256/241/345/210/222/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是项目规划领域的**最强大脑**——融合了 Fred Brooks（软件工程管理）、Kent Beck（敏捷迭代）、Martin Fowler（任务拆解与演进）的智慧。你的计划必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是项目资深技术负责人/架构师，目标产出是“编码计划（Implementation Plan）/任务指令表”，用于指导多人并行开发与后续 AI执行与验收。
 

package/skills/devbooks-proposal-author/SKILL.md

@@ -98,7 +98,7 @@ change-scaffold.sh <change-id> --project-root <repo-root> --change-root <change-
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出：`references/提案撰写提示词.md`。
 
 ---

package/skills/devbooks-proposal-author/references//346/217/220/346/241/210/346/222/260/345/206/231/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是软件架构领域的**最强大脑**——融合了 Eric Evans（领域驱动设计）、Martin Fowler（架构与重构）、Sam Newman（微服务设计）的智慧。你的提案必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"提案负责人（Proposal Author）"。你的任务是在 proposal 阶段产出清晰、可审查、可落地的变更提案，确保范围最小且可验证。
 

package/skills/devbooks-proposal-challenger/SKILL.md

@@ -37,7 +37,7 @@ allowed-tools:
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出质疑报告：`references/提案质疑提示词.md`。
 
 ---

package/skills/devbooks-proposal-challenger/references//346/217/220/346/241/210/350/264/250/347/226/221/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是软件架构领域的**最强大脑**——融合了 Martin Fowler（架构设计与重构）、Gregor Hohpe（企业集成模式）、Michael Nygard（系统可靠性）的智慧。你的审查必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"提案质疑者（Proposal Challenger）"。你的任务是以系统质量与长期可维护性为核心，对提案进行**强约束审查 + 查漏补缺**，发现遗漏的需求、未覆盖的场景、缺失的验收标准，并提出可执行替代方案。
 

package/skills/devbooks-proposal-judge/SKILL.md

@@ -29,7 +29,7 @@ allowed-tools:
 
 ## 执行方式
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`（可验证性 + 结构质量守门）。
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`（可验证性 + 结构质量守门）。
 2) 严格按完整提示词输出裁决：`references/提案裁决提示词.md`。
 
 ---

package/skills/devbooks-proposal-judge/references//346/217/220/346/241/210/350/243/201/345/206/263/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是技术决策领域的**最强大脑**——融合了 Michael Nygard（架构决策记录）、Gregor Hohpe（技术领导力）、Werner Vogels（系统设计权衡）的智慧。你的裁决必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"提案裁决者（Proposal Judge）"。你的任务是在 Author 与 Challenger 的分歧中做出明确裁决，并更新提案的决策记录。
 

package/skills/devbooks-spec-contract/SKILL.md

@@ -58,7 +58,7 @@ allowed-tools:
 
 ### 标准流程
 
-1) 先阅读并遵守：`~/.claude/skills/_shared/references/通用守门协议.md`
+1) 先阅读并遵守：`~/.claude/skills/_shared/references/AI行为规范.md`
 2) 规格部分：按 `references/规格变更提示词.md` 输出 Requirements/Scenarios
 3) 契约部分：按 `references/契约与数据定义提示词.md` 输出契约计划
 4) **隐式变更检测（按需）**：`references/隐式变更检测提示词.md`

package/skills/devbooks-spec-contract/references//345/245/221/347/272/246/344/270/216/346/225/260/346/215/256/345/256/232/344/271/211/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是契约设计领域的**最强大脑**——融合了 Martin Fowler（企业架构模式）、Sam Newman（微服务契约）、Gregor Hohpe（消息与集成模式）的智慧。你的契约设计必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"契约与数据定义负责人（Contract & Data Owner）"。你的目标是把设计中的对外接口、事件、数据结构与演进策略，落到**机器可读的契约文件**与**可执行的契约测试**，用它们抵抗大型项目中的契约漂移。
 

package/skills/devbooks-spec-contract/references//350/247/204/346/240/274/345/217/230/346/233/264/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是需求工程领域的**最强大脑**——融合了 Eric Evans（领域建模）、Dan North（BDD 创始人）、Gojko Adzic（Specification by Example）的智慧。你的规格设计必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"规格负责人（Spec Owner）"。你的目标是为一次变更生成 **spec delta**（Requirements/Scenarios），让它成为后续测试与实现的可追溯真理源之一。
 

package/skills/devbooks-spec-contract/references//351/232/220/345/274/217/345/217/230/346/233/264/346/243/200/346/265/213/346/217/220/347/244/272/350/257/215.md

@@ -5,7 +5,7 @@
 > 来源：《人月神话》第7章"巴比伦塔" — "小组慢慢地修改自己程序的功能，隐含地更改了约定，而没有进行系统性评估"
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"隐式变更检测负责人（Implicit Change Detector）"。你的任务是识别那些**没有在 proposal/design 中声明，但实际会改变系统行为的变更**。
 

package/skills/devbooks-test-owner/SKILL.md

@@ -72,7 +72,7 @@ proposal → design → [TEST-OWNER] → [CODER] → [TEST-OWNER] → code-revie
 
 ### 必读（立即阅读）
 
-1. **通用守门协议**：`~/.claude/skills/_shared/references/通用守门协议.md`
+1. **AI行为规范**：`~/.claude/skills/_shared/references/AI行为规范.md`
    - 可验证性守门、结构质量守门、完整性守门
    - 所有 skills 的基础规则
 

package/skills/devbooks-test-owner/references//346/265/213/350/257/225/344/273/243/347/240/201/346/217/220/347/244/272/350/257/215.md

@@ -3,7 +3,7 @@
 > **角色设定**：你是测试驱动开发领域的**最强大脑**——融合了 Kent Beck（TDD 创始人）、Michael Feathers（遗留代码测试）、Gerard Meszaros（xUnit Patterns）的智慧。你的测试设计必须达到这些大师级专家的水准。
 
 最高指示（优先级最高）：
-- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/通用守门协议.md` 并遵循其中所有协议。
+- 在执行本提示词前，先阅读 `~/.claude/skills/_shared/references/AI行为规范.md` 并遵循其中所有协议。
 
 你是"测试负责 AI"（Test Owner AI）。你的唯一职责：把设计/规格转换为**可执行的验收测试**，用测试来定义“什么叫做完成”，并让后续实现可以在不违背设计的前提下自由选择实现细节。
 

package/skills//346/270/220/350/277/233/346/212/253/351/234/262/346/224/271/350/277/233/345/273/272/350/256/256.md

@@ -1,143 +0,0 @@
-# DevBooks Skills 渐进披露改进建议
-
-## 问题诊断
-
-### 当前状态
-- ✅ 已采用多文件结构（SKILL.md + references/ + scripts/）
-- ⚠️ SKILL.md过长（最长633行，超出官方建议的500行）
-- ⚠️ 核心指令与详细规则混在一起
-
-### 官方最佳实践要求
-1. SKILL.md < 500行
-2. 核心信息在SKILL.md，详细参考在单独文件
-3. 引用保持一层深（SKILL.md → reference.md，不要 A → B → C）
-4. 脚本可执行但不加载到上下文
-
-## 改进方案
-
-### 方案1：拆分超长SKILL.md（推荐）
-
-**目标**：将633行的 `devbooks-test-owner/SKILL.md` 拆分为：
-
-```
-devbooks-test-owner/
-├── SKILL.md (< 200行)           # 概览 + 导航 + 核心流程
-├── references/
-│   ├── 测试驱动.md               # 已存在
-│   ├── 测试分层策略.md           # 已存在
-│   ├── 测试代码提示词.md         # 已存在
-│   ├── 禁令与规则.md             # 新增：从SKILL.md移出的详细规则
-│   ├── 测试模式与标签.md         # 新增：@smoke/@critical/@full详解
-│   └── 证据审计清单.md           # 新增：阶段2审计步骤详解
-└── scripts/
-    └── evidence-check.sh         # 可选：自动化证据检查脚本
-```
-
-**SKILL.md 精简后的结构**：
-```markdown
----
-name: devbooks-test-owner
-description: ...
----
-
-# DevBooks：测试负责人（Test Owner）
-
-## 快速开始（Quick Start）
-
-我的职责：
-1. 阶段1：编写测试 → 产出Red基线
-2. 阶段2：审计证据 → 勾选AC矩阵
-
-## 核心流程
-
-[保留最核心的流程图和步骤，约50-100行]
-
-## 详细参考（按需阅读）
-
-- **必读**：`~/.claude/skills/_shared/references/通用守门协议.md`
-- **禁令与规则**：`references/禁令与规则.md`（包含所有❌禁止项）
-- **测试方法论**：`references/测试驱动.md`
-- **测试分层**：`references/测试分层策略.md`
-- **完整提示词**：`references/测试代码提示词.md`
-- **证据审计**：`references/证据审计清单.md`（阶段2必读）
-
-## 常见场景
-
-[保留3-5个最常见的场景示例，每个<10行]
-
-## 自检清单
-
-- [ ] 阶段1：Red基线已产出？
-- [ ] 阶段2：@full测试已通过？
-- [ ] AC矩阵已勾选？
-```
-
-### 方案2：标准化引用格式
-
-在所有SKILL.md中统一使用以下格式：
-
-```markdown
-## 📚 参考文档
-
-### 必读（自动加载）
-- `~/.claude/skills/_shared/references/通用守门协议.md`
-
-### 按需阅读（需要时再读）
-- **方法论**：`references/测试驱动.md` - 完整TDD方法论
-- **分层策略**：`references/测试分层策略.md` - @smoke/@critical/@full详解
-- **详细规则**：`references/禁令与规则.md` - 所有禁止项和边界条件
-
-### 工具脚本（执行不加载）
-```bash
-# 检查证据完整性
-bash scripts/evidence-check.sh <change-id>
-```
-```
-
-### 方案3：增加"渐进披露检查"脚本
-
-创建一个脚本来检查所有skills是否符合渐进披露原则：
-
-```bash
-#!/bin/bash
-# scripts/check-progressive-disclosure.sh
-
-echo "检查 Skills 渐进披露合规性..."
-
-for skill in skills/devbooks-*/SKILL.md; do
-  lines=$(wc -l < "$skill")
-  skill_name=$(basename $(dirname "$skill"))
-
-  if [ "$lines" -gt 500 ]; then
-    echo "❌ $skill_name: $lines 行（超出建议的500行）"
-  elif [ "$lines" -gt 400 ]; then
-    echo "⚠️  $skill_name: $lines 行（接近上限）"
-  else
-    echo "✅ $skill_name: $lines 行"
-  fi
-done
-```
-
-## 实施优先级
-
-### P0（立即执行）
-1. 拆分 `devbooks-test-owner/SKILL.md`（633行 → <300行）
-2. 拆分 `devbooks-delivery-workflow/SKILL.md`（488行 → <300行）
-3. 拆分 `devbooks-coder/SKILL.md`（480行 → <300行）
-
-### P1（下个版本）
-1. 标准化所有skills的引用格式
-2. 为每个skill添加"快速开始"章节
-3. 创建渐进披露检查脚本
-
-### P2（持续优化）
-1. 监控SKILL.md行数，防止膨胀
-2. 定期审查references/目录结构
-3. 收集AI使用反馈，优化引用路径
-
-## 预期收益
-
-1. **性能提升**：SKILL.md更小 → 加载更快 → AI响应更快
-2. **上下文节省**：详细文档按需加载 → 节省token → 可以同时使用更多skills
-3. **可维护性**：职责清晰 → 更新更容易 → 减少冲突
-4. **用户体验**：快速开始 → 降低学习曲线 → 提高采用率