@zhuan-ai/zhuanspec 1.3.0

package/dist/core/templates/agents-template.js

@@ -0,0 +1,706 @@
+export const agentsTemplate = `# ZhuanSpec 使用说明
+
+面向使用 ZhuanSpec 进行规范驱动开发的 AI 编程助手的说明文档。
+
+## 快速检查清单
+
+- 搜索现有工作：\`zhuanspec spec list --long\`、\`zhuanspec list\`（仅使用 \`rg\` 进行全文搜索）
+- 确定范围：新功能 vs 修改现有功能
+- 选择唯一的 \`change-id\`：kebab-case 格式，动词开头（\`add-\`、\`update-\`、\`remove-\`、\`refactor-\`）
+- 搭建结构：\`proposal.md\`、\`tasks.md\`、\`design.md\`（仅在需要时），以及每个受影响功能的规范增量
+- 编写增量：使用 \`## ADDED|MODIFIED|REMOVED|RENAMED Requirements\`；每个要求至少包含一个 \`#### Scenario:\`
+- 验证：运行 \`zhuanspec validate [change-id] --strict\` 并修复问题
+- 请求批准：在提案获得批准之前不要开始实施
+
+## 三阶段工作流
+
+### 阶段 1：创建变更
+在以下情况下创建提案：
+- 添加功能或特性
+- 进行破坏性更改（API、schema）
+- 更改架构或模式
+- 优化性能（改变行为）
+- 更新安全模式
+
+触发词示例：
+- "帮我创建一个变更提案"
+- "帮我规划一个变更"
+- "帮我创建一个提案"
+- "我想创建一个规范提案"
+- "我想创建一个规范"
+
+宽松匹配指导：
+- 包含以下之一：\`proposal\`、\`change\`、\`spec\`
+- 与以下之一组合：\`create\`、\`plan\`、\`make\`、\`start\`、\`help\`
+
+跳过提案的情况：
+- Bug 修复（恢复预期行为）
+- 拼写错误、格式、注释
+- 依赖更新（非破坏性）
+- 配置更改
+- 现有行为的测试
+
+**工作流**
+0. 审查 \`zhuanspec/project.md\`、\`zhuanspec list\` 和 \`zhuanspec list --specs\` 以了解当前上下文。
+1. **强制澄清检查（必须首先执行）**：分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、实现细节、数据获取来源、服务分层、依赖关系、优先级、验收标准等......）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测或创建提案，严禁要求用户手动输入大段文字。
+2. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\`、可选的 \`design.md\` 和规范增量。
+3. 使用 \`## ADDED|MODIFIED|REMOVED Requirements\` 起草规范增量，每个要求至少包含一个 \`#### Scenario:\`。
+4. 运行 \`zhuanspec validate <id> --strict\` 并在分享提案之前解决所有问题。
+
+### 阶段 2：实施变更
+将这些步骤作为待办事项跟踪，逐一完成。
+1. **阅读 proposal.md** - 了解要构建的内容
+2. **阅读 design.md**（如果存在） - 审查技术决策
+3. **阅读 tasks.md** - 获取实施清单
+4. **按顺序实施任务** - 按顺序完成。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill
+5. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成
+6. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`，以便列表反映实际情况
+7. **代码审查**（可选） - 基于生成的上下文文件审查已实施的代码，检查：
+   - 代码规范和约定合规性
+   - 逻辑正确性
+   - 性能问题和潜在瓶颈
+   - 安全性问题
+   - 最佳实践遵循情况
+   - 对于 Java 代码：特别关注 Java 特定的模式、约定和潜在问题
+   - 此步骤是可选的，如果跳过不会阻塞工作流
+   - 如果发现问题，应在归档之前解决
+8. **批准门槛** - 在提案经过审查和批准之前不要开始实施
+
+### 阶段 3：归档变更
+部署后，创建单独的 PR：
+- 将 \`changes/[name]/\` → \`changes/archive/YYYY-MM-DD-[name]/\`
+- 如果功能已更改，更新 \`specs/\`
+- 对于仅工具类的变更，使用 \`zhuanspec archive <change-id> --skip-specs --yes\`（始终显式传递变更 ID）
+- 运行 \`zhuanspec validate --strict\` 以确认归档的变更通过检查
+
+## 执行任何任务之前
+
+**上下文检查清单：**
+- [ ] 在 \`specs/[capability]/spec.md\` 中阅读相关规范
+- [ ] 检查 \`changes/\` 中的待处理变更是否存在冲突
+- [ ] 阅读 \`zhuanspec/project.md\` 了解约定
+- [ ] 运行 \`zhuanspec list\` 查看活动变更
+- [ ] 运行 \`zhuanspec list --specs\` 查看现有功能
+
+**创建规范之前：**
+- 始终检查功能是否已存在
+- 优先修改现有规范而不是创建重复项
+- 使用 \`zhuanspec show [spec]\` 审查当前状态
+- **强制澄清要求**：如果请求有任何不明确、模糊或不确定的方面，必须停止并使用**选项式交互**提问。严禁在不确定的情况下自行推测、假设或继续创建文件。严禁要求用户手动输入大段文字回答。
+
+## 强制澄清工作流
+
+在创建任何提案文件之前，必须执行强制澄清检查。这是不可跳过的步骤。
+
+**重要原则：先查阅后询问，避免过度询问**
+
+在询问之前，必须先查阅以下来源，只有在确实无法从这些来源确定时才询问：
+- 现有规范（\`zhuanspec/specs/\`）
+- 项目约定（\`zhuanspec/project.md\`）
+- 代码库结构和现有模式
+- 上下文文件和相关变更
+
+### 何时需要澄清
+
+在以下情况下，**且无法从现有规范、项目约定、代码库结构中确定时**，必须停止并提问（包括但不限于）：
+- **范围不明确**：用户请求的范围边界不清楚（例如："改进性能"、"优化代码"）
+- **技术选择不明确**：有多种实现方式，但用户未指定偏好，且无法从现有代码模式中确定（例如：使用哪种数据库、哪种框架）
+- **优先级不明确**：多个需求但未说明优先级或顺序
+- **验收标准不明确**：不清楚如何判断完成或成功
+- **实现细节不明确**：不清楚如何实现或实现细节不明确，且无法从代码库分析中确定（例如：如何获取数据、如何处理错误、如何优化性能）
+- **代码改动位置不明确**：不清楚需要修改哪些文件、在哪些位置进行修改，且无法从代码库结构分析中确定
+- **代码分层架构不明确**：如果涉及服务分层（如 4 层架构、3 层架构等），不清楚各层的职责和改动位置，且无法从现有代码结构或规范中确定
+- **数据获取来源不明确**：不清楚从哪里获取数据，且无法从现有代码或规范中确定（例如：从数据库、API、文件、外部服务、历史逻辑复用）
+- **服务分层不明确**：不清楚服务分层，且无法从现有代码结构或规范中确定（例如：前端、后端、数据库、API、服务、4层架构、3层架构、2层架构、领域模型）
+- **依赖关系不明确**：不清楚依赖关系，且无法从代码库分析中确定（例如：依赖哪些服务、依赖哪些库、依赖哪些组件）
+- **上下文信息缺失**：缺少必要的背景信息来理解需求，且无法从现有规范或代码中获取
+- **歧义性表述**：用户请求可以用多种方式理解，且无法从上下文确定
+- **其他不明确**：其他不明确的情况，且无法从现有来源确定
+
+### 何时不需要澄清
+
+在以下情况下，**不应询问**，应直接使用从现有来源获取的信息：
+- **信息已明确**：用户请求中已经明确说明了相关信息
+- **可从规范获取**：信息可以从现有规范（\`zhuanspec/specs/\`）中获取
+- **可从项目约定获取**：信息可以从项目约定（\`zhuanspec/project.md\`）中获取
+- **可从代码库分析获取**：信息可以通过分析代码库结构、现有模式、相关文件获取
+- **可从上下文获取**：信息可以从上下文文件、相关变更、历史记录中获取
+- **符合常见模式**：实现方式符合项目中的常见模式或最佳实践，无需特别询问
+
+**原则**：如果可以通过查阅现有来源确定信息，就不要询问用户，以提高效率。
+
+### 澄清问题格式
+
+**必须使用选项式交互，严禁要求用户手动输入文字回答。**
+
+使用编辑器提供的结构化问答工具（如 Cursor 的 \`AskQuestion\` 工具、Claude Code 的交互式选择等）向用户提问，将每个澄清问题转化为带预设选项的选择题：
+
+**格式要求：**
+- 每个问题提供 2-5 个预设选项
+- 每个问题末尾包含一个"其他"选项，以覆盖未列出的情况
+- 允许用户多选（当问题可能有多个答案时设置 \`allow_multiple: true\`）
+- 选项文本要简洁明了，必要时附带简短说明
+- 如果有多个独立的澄清问题，合并到同一次问答交互中（一次性展示多个问题）
+
+**标准格式模板：**
+
+\`\`\`
+使用 AskQuestion 工具提问，结构如下：
+
+问题 1: "关于 [不确定的方面]：[具体问题]"
+选项：
+  A) [选项1 - 简短说明]
+  B) [选项2 - 简短说明]
+  C) [选项3 - 简短说明]
+  D) 其他（请在后续补充说明）
+
+问题 2: "关于 [另一个方面]：[具体问题]"
+选项：
+  A) [选项1]
+  B) [选项2]
+  C) 其他
+\`\`\`
+
+**工具调用示例（Cursor AskQuestion）：**
+\`\`\`json
+{
+  "questions": [
+    {
+      "id": "scope",
+      "prompt": "关于改进范围：您希望改进哪些方面？",
+      "options": [
+        {"id": "security", "label": "安全性（如双因素认证）"},
+        {"id": "ux", "label": "用户体验（如简化流程）"},
+        {"id": "performance", "label": "性能（如响应时间优化）"},
+        {"id": "other", "label": "其他"}
+      ],
+      "allow_multiple": true
+    },
+    {
+      "id": "priority",
+      "prompt": "如果有多个改进点，优先级如何？",
+      "options": [
+        {"id": "security_first", "label": "安全性优先"},
+        {"id": "ux_first", "label": "用户体验优先"},
+        {"id": "all_equal", "label": "同等重要，一起做"}
+      ]
+    }
+  ]
+}
+\`\`\`
+
+**原则：**
+- 永远不要让用户从零开始输入答案，总是提供可选的选项
+- 选项应覆盖最常见的答案场景
+- "其他"选项作为兜底，确保不遗漏特殊情况
+- 用户选择"其他"后，再针对性地追问细节
+
+### 禁止行为
+
+在遇到模糊需求时，**严禁**以下行为：
+- ❌ 自行推测用户意图
+- ❌ 基于"最佳猜测"创建提案
+- ❌ 假设用户想要什么
+- ❌ 跳过澄清直接创建文件
+- ❌ 使用模糊的表述来掩盖不确定性
+- ❌ 要求用户手动输入大段文字来回答澄清问题（必须使用选项式交互）
+
+### 澄清流程
+
+1. **查阅现有来源**：首先查阅现有规范、项目约定、代码库结构、上下文文件等，尝试从这些来源获取所需信息
+2. **识别模糊点**：仔细分析用户请求，列出所有不确定的方面，**但排除那些可以从现有来源确定的方面**
+3. **判断是否需要询问**：对于每个不确定的方面，判断是否可以从现有来源确定：
+   - 如果可以确定，则使用从现有来源获取的信息，不询问
+   - 如果无法确定，则标记为需要询问
+4. **构造选项式问题**：将所有需要询问的模糊点转化为带预设选项的选择题，尽量合并到一次交互中
+5. **使用工具提问**：调用编辑器的结构化问答工具（如 \`AskQuestion\`）一次性展示所有问题和选项，等待用户选择
+6. **等待用户选择**：必须等待用户选择答案，不能继续
+7. **处理"其他"选项**：如果用户选择了"其他"，再针对该问题追问具体细节（仍优先使用选项式，如确实无法预设则允许简短文字输入）
+8. **确认理解**：在开始创建文件前，简要总结理解以确保准确
+9. **开始创建**：只有在所有必要的模糊点都明确后，才能开始创建提案文件
+
+### 示例
+
+**用户请求**："改进登录功能"
+
+**分析过程**：
+1. 首先查阅现有规范（\`zhuanspec/specs/\`）中是否有登录相关的规范
+2. 查阅项目约定（\`zhuanspec/project.md\`）了解项目架构和约定
+3. 分析代码库结构，了解现有的登录实现方式
+4. 如果从这些来源无法确定改进范围，则使用选项式交互询问
+
+**必须使用选项式交互提问**（仅在无法从现有来源确定时）：
+
+\`\`\`json
+{
+  "questions": [
+    {
+      "id": "improvement_scope",
+      "prompt": "您希望改进登录功能的哪些方面？",
+      "options": [
+        {"id": "security", "label": "安全性（如添加双因素认证）"},
+        {"id": "ux", "label": "用户体验（如简化登录流程）"},
+        {"id": "performance", "label": "性能（如优化登录响应时间）"},
+        {"id": "other", "label": "其他"}
+      ],
+      "allow_multiple": true
+    },
+    {
+      "id": "tech_preference",
+      "prompt": "您有特定的技术偏好吗？",
+      "options": [
+        {"id": "jwt", "label": "JWT Token 认证"},
+        {"id": "session", "label": "Session 认证"},
+        {"id": "oauth", "label": "OAuth 第三方集成"},
+        {"id": "no_preference", "label": "无偏好，由你推荐"},
+        {"id": "other", "label": "其他"}
+      ]
+    },
+    {
+      "id": "priority",
+      "prompt": "如果有多个改进点，优先级如何？",
+      "options": [
+        {"id": "security_first", "label": "安全性优先"},
+        {"id": "ux_first", "label": "用户体验优先"},
+        {"id": "perf_first", "label": "性能优先"},
+        {"id": "all_equal", "label": "同等重要，一起做"}
+      ]
+    }
+  ]
+}
+\`\`\`
+
+**实现细节相关示例**（仅在无法从代码库分析确定时询问）：
+
+**用户请求**："重构用户认证服务"
+
+**如果无法从代码库分析确定，使用选项式交互提问**：
+
+\`\`\`json
+{
+  "questions": [
+    {
+      "id": "change_scope",
+      "prompt": "重构涉及哪些改动？",
+      "options": [
+        {"id": "modify_existing", "label": "修改现有认证服务类"},
+        {"id": "new_service", "label": "创建新的服务层"},
+        {"id": "both", "label": "两者都涉及"},
+        {"id": "other", "label": "其他"}
+      ]
+    },
+    {
+      "id": "layer_scope",
+      "prompt": "改动应该在哪些层进行？",
+      "options": [
+        {"id": "controller", "label": "Controller 层"},
+        {"id": "service", "label": "Service 层"},
+        {"id": "repository", "label": "Repository 层"},
+        {"id": "all", "label": "全部层"}
+      ],
+      "allow_multiple": true
+    },
+    {
+      "id": "refactor_strategy",
+      "prompt": "重构策略偏好？",
+      "options": [
+        {"id": "incremental", "label": "渐进式重构（逐步替换）"},
+        {"id": "rewrite", "label": "完全重写"},
+        {"id": "strangler", "label": "绞杀者模式（新旧并行后切换）"},
+        {"id": "no_preference", "label": "无偏好，由你推荐"}
+      ]
+    }
+  ]
+}
+\`\`\`
+
+**注意**：如果可以从现有代码结构、规范或项目约定中确定这些信息，则不应询问，直接使用从现有来源获取的信息。
+
+### 搜索指导
+- 枚举规范：\`zhuanspec spec list --long\`（或使用 \`--json\` 用于脚本）
+- 枚举变更：\`zhuanspec list\`（或 \`zhuanspec change list --json\` - 已弃用但可用）
+- 显示详细信息：
+  - 规范：\`zhuanspec show <spec-id> --type spec\`（使用 \`--json\` 进行过滤）
+  - 变更：\`zhuanspec show <change-id> --json --deltas-only\`
+- 全文搜索（使用 ripgrep）：\`rg -n "Requirement:|Scenario:" zhuanspec/specs\`
+
+## 快速开始
+
+### CLI 命令
+
+\`\`\`bash
+# 基本命令
+zhuanspec list                  # 列出活动变更
+zhuanspec list --specs          # 列出规范
+zhuanspec show [item]           # 显示变更或规范
+zhuanspec validate [item]       # 验证变更或规范
+zhuanspec archive <change-id> [--yes|-y]   # 部署后归档（添加 --yes 用于非交互式运行）
+
+# 项目管理
+zhuanspec init [path]           # 初始化 ZhuanSpec
+zhuanspec update [path]         # 更新说明文件
+
+# 交互模式
+zhuanspec show                  # 提示选择
+zhuanspec validate              # 批量验证模式
+
+# 调试
+zhuanspec show [change] --json --deltas-only
+zhuanspec validate [change] --strict
+\`\`\`
+
+### 命令标志
+
+- \`--json\` - 机器可读输出
+- \`--type change|spec\` - 消除项目歧义
+- \`--strict\` - 全面验证
+- \`--no-interactive\` - 禁用提示
+- \`--skip-specs\` - 归档时不更新规范
+- \`--yes\`/\`-y\` - 跳过确认提示（非交互式归档）
+
+## 目录结构
+
+\`\`\`
+zhuanspec/
+├── project.md              # 项目约定
+├── specs/                  # 当前真实状态 - 已构建的内容
+│   └── [capability]/       # 单一聚焦的功能
+│       ├── spec.md         # 要求和场景
+│       └── design.md       # 技术模式
+├── changes/                # 提案 - 应该更改的内容
+│   ├── [change-name]/
+│   │   ├── proposal.md     # 原因、内容、影响
+│   │   ├── tasks.md        # 实施清单
+│   │   ├── design.md       # 技术决策（可选；见标准）
+│   │   └── specs/          # 增量变更
+│   │       └── [capability]/
+│   │           └── spec.md # ADDED/MODIFIED/REMOVED
+│   └── archive/            # 已完成的变更
+\`\`\`
+
+## 创建变更提案
+
+### 决策树
+
+\`\`\`
+新请求？
+├─ 修复恢复规范行为的 Bug？ → 直接修复
+├─ 拼写错误/格式/注释？ → 直接修复
+├─ 新功能/能力？ → 创建提案
+├─ 破坏性更改？ → 创建提案
+├─ 架构更改？ → 创建提案
+└─ 不明确？ → 创建提案（更安全）
+\`\`\`
+
+### 提案结构
+
+1. **创建目录：** \`changes/[change-id]/\`（kebab-case，动词开头，唯一）
+
+2. **编写 proposal.md：**
+\`\`\`markdown
+# Change: [变更的简要描述]
+
+## Why
+[关于问题/机会的 1-2 句话]
+
+## What Changes
+- [变更的要点列表]
+- [用 **BREAKING** 标记破坏性更改]
+
+## Impact
+- Affected specs: [列出功能]
+- Affected code: [关键文件/系统]
+\`\`\`
+
+3. **创建规范增量：** \`specs/[capability]/spec.md\`
+\`\`\`markdown
+## ADDED Requirements
+### Requirement: New Feature
+The system SHALL provide...
+
+#### Scenario: Success case
+- **WHEN** user performs action
+- **THEN** expected result
+
+## MODIFIED Requirements
+### Requirement: Existing Feature
+[完整的修改后要求]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason**: [移除原因]
+**Migration**: [如何处理]
+\`\`\`
+如果多个功能受到影响，在 \`changes/[change-id]/specs/<capability>/spec.md\` 下创建多个增量文件——每个功能一个。
+
+4. **创建 tasks.md：**
+
+先运行 \`zhuanspec skills list --json\` 发现当前环境中可用的 skill 及其 description，然后基于语义匹配在任务中标注真实 skill 名称：
+
+\`\`\`markdown
+## 1. Implementation
+- [ ] 1.1 Create database schema @skill:java-db-schema-standards
+- [ ] 1.2 Implement RPC interface @skill:java-scf-rpc-usage-skill
+- [ ] 1.3 Add frontend component @skill:kf-fe-frontend-dev
+- [ ] 1.4 Write tests @skill:generate-mockito-unit-test-skill
+\`\`\`
+> **@skill 标签**：创建 tasks.md 前，运行 \`zhuanspec skills list --json\` 发现可用 skill 及其 description。基于 skill description 进行语义匹配：
+> - 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+> - 只有当任务功能与 skill description 明确匹配时才标注
+> - 简单的代码修改（如增删枚举值）应匹配通用编码规范 skill，而非架构级 skill
+> - 避免仅因文件名或路径关键词而错误匹配
+> - 使用真实 skill 名称标注，支持多个 skill（\`@skill:name1,name2\`）
+> - Apply 阶段 AI 根据标签直接调用对应 skill。无可用 skill 时可省略。
+
+5. **在需要时创建 design.md：**
+如果以下任何情况适用，则创建 \`design.md\`；否则省略：
+- 横切变更（多个服务/模块）或新的架构模式
+- 新的外部依赖或重要的数据模型更改
+- 安全性、性能或迁移复杂性
+- 在编码之前从技术决策中受益的模糊性
+
+最小 \`design.md\` 骨架：
+\`\`\`markdown
+## Context
+[背景、约束、利益相关者]
+
+## Goals / Non-Goals
+- Goals: [...]
+- Non-Goals: [...]
+
+## Decisions
+- Decision: [内容和原因]
+- Alternatives considered: [选项 + 理由]
+
+## Risks / Trade-offs
+- [风险] → 缓解措施
+
+## Migration Plan
+[步骤、回滚]
+
+## Open Questions
+- [...]
+\`\`\`
+
+## 规范文件格式
+
+### 关键：场景格式
+
+**正确**（使用 #### 标题）：
+\`\`\`markdown
+#### Scenario: User login success
+- **WHEN** valid credentials provided
+- **THEN** return JWT token
+\`\`\`
+
+**错误**（不要使用项目符号或粗体）：
+\`\`\`markdown
+- **Scenario: User login**  ❌
+**Scenario**: User login     ❌
+### Scenario: User login      ❌
+\`\`\`
+
+每个要求必须至少有一个场景。
+
+### 要求措辞
+- 对规范性要求使用 SHALL/MUST（除非有意非规范性，否则避免使用 should/may）
+
+### 增量操作
+
+- \`## ADDED Requirements\` - 新功能
+- \`## MODIFIED Requirements\` - 更改的行为
+- \`## REMOVED Requirements\` - 已弃用的功能
+- \`## RENAMED Requirements\` - 名称更改
+
+标题使用 \`trim(header)\` 匹配 - 忽略空白。
+
+#### 何时使用 ADDED vs MODIFIED
+- ADDED：引入一个新的功能或子功能，可以独立作为要求。当更改是正交的（例如，添加"斜杠命令配置"）而不是改变现有要求的语义时，优先使用 ADDED。
+- MODIFIED：更改现有要求的行为、范围或验收标准。始终粘贴完整的、更新的要求内容（标题 + 所有场景）。归档器将用您在此处提供的内容替换整个要求；部分增量将丢失先前的详细信息。
+- RENAMED：仅在名称更改时使用。如果您还更改行为，请使用 RENAMED（名称）加上 MODIFIED（内容），引用新名称。
+
+常见陷阱：使用 MODIFIED 添加新关注点而不包含先前的文本。这会在归档时导致详细信息丢失。如果您没有明确更改现有要求，请在 ADDED 下添加新要求。
+
+正确编写 MODIFIED 要求：
+1) 在 \`zhuanspec/specs/<capability>/spec.md\` 中找到现有要求。
+2) 复制整个要求块（从 \`### Requirement: ...\` 到其场景）。
+3) 将其粘贴到 \`## MODIFIED Requirements\` 下并编辑以反映新行为。
+4) 确保标题文本完全匹配（忽略空白）并至少保留一个 \`#### Scenario:\`。
+
+RENAMED 示例：
+\`\`\`markdown
+## RENAMED Requirements
+- FROM: \`### Requirement: Login\`
+- TO: \`### Requirement: User Authentication\`
+\`\`\`
+
+## 故障排除
+
+### 常见错误
+
+**"变更必须至少有一个增量"**
+- 检查 \`changes/[name]/specs/\` 是否存在 .md 文件
+- 验证文件具有操作前缀（## ADDED Requirements）
+
+**"要求必须至少有一个场景"**
+- 检查场景是否使用 \`#### Scenario:\` 格式（4 个井号）
+- 不要对场景标题使用项目符号或粗体
+
+**静默场景解析失败**
+- 需要精确格式：\`#### Scenario: Name\`
+- 使用以下命令调试：\`zhuanspec show [change] --json --deltas-only\`
+
+### 验证提示
+
+\`\`\`bash
+# 始终使用严格模式进行全面检查
+zhuanspec validate [change] --strict
+
+# 调试增量解析
+zhuanspec show [change] --json | jq '.deltas'
+
+# 检查特定要求
+zhuanspec show [spec] --json -r 1
+\`\`\`
+
+## 理想路径脚本
+
+\`\`\`bash
+# 1) 探索当前状态
+zhuanspec spec list --long
+zhuanspec list
+# 可选全文搜索：
+# rg -n "Requirement:|Scenario:" zhuanspec/specs
+# rg -n "^#|Requirement:" zhuanspec/changes
+
+# 2) 选择变更 ID 并搭建
+CHANGE=add-two-factor-auth
+mkdir -p zhuanspec/changes/\$CHANGE/{specs/auth}
+printf "## Why\\n...\\n\\n## What Changes\\n- ...\\n\\n## Impact\\n- ...\\n" > zhuanspec/changes/\$CHANGE/proposal.md
+printf "## 1. Implementation\\n- [ ] 1.1 ...\\n" > zhuanspec/changes/\$CHANGE/tasks.md
+
+# 3) 添加增量（示例）
+cat > zhuanspec/changes/\$CHANGE/specs/auth/spec.md << 'EOF'
+## ADDED Requirements
+### Requirement: 双因素认证
+用户 MUST 在登录时提供第二个认证因素。
+
+#### Scenario: 需要 OTP
+- **WHEN** 提供了有效凭据
+- **THEN** 需要 OTP 挑战
+EOF
+
+# 4) 验证
+zhuanspec validate \$CHANGE --strict
+\`\`\`
+
+## Multi-Capability Example
+
+\`\`\`
+zhuanspec/changes/add-2fa-notify/
+├── proposal.md
+├── tasks.md
+└── specs/
+    ├── auth/
+    │   └── spec.md   # ADDED: 双因素认证
+    └── notifications/
+        └── spec.md   # ADDED: OTP 邮件通知
+\`\`\`
+
+auth/spec.md
+\`\`\`markdown
+## ADDED Requirements
+### Requirement: 双因素认证
+...
+\`\`\`
+
+notifications/spec.md
+\`\`\`markdown
+## ADDED Requirements
+### Requirement: OTP 邮件通知
+...
+\`\`\`
+
+## 最佳实践
+
+### 简单优先
+- 默认新增代码 <100 行
+- 单文件实现，直到证明不足
+- 避免没有明确理由的框架
+- 选择无聊但经过验证的模式
+
+### 复杂性触发条件
+仅在以下情况下添加复杂性：
+- 性能数据表明当前解决方案太慢
+- 具体的规模要求（>1000 用户，>100MB 数据）
+- 多个经过验证的用例需要抽象
+
+### 清晰的引用
+- 使用 \`file.ts:42\` 格式表示代码位置
+- 将规范引用为 \`specs/auth/spec.md\`
+- 链接相关变更和 PR
+
+### 功能命名
+- 使用动词-名词：\`user-auth\`、\`payment-capture\`
+- 每个功能单一目的
+- 10 分钟可理解性规则
+- 如果描述需要"AND"，则拆分
+
+### 变更 ID 命名
+- 使用 kebab-case，简短且描述性：\`add-two-factor-auth\`
+- 优先使用动词开头的前缀：\`add-\`、\`update-\`、\`remove-\`、\`refactor-\`
+- 确保唯一性；如果已使用，追加 \`-2\`、\`-3\` 等
+
+## 工具选择指南
+
+| 任务 | 工具 | 原因 |
+|------|------|-----|
+| 按模式查找文件 | Glob | 快速模式匹配 |
+| 搜索代码内容 | Grep | 优化的正则表达式搜索 |
+| 读取特定文件 | Read | 直接文件访问 |
+| 探索未知范围 | Task | 多步骤调查 |
+
+## 错误恢复
+
+### 变更冲突
+1. 运行 \`zhuanspec list\` 查看活动变更
+2. 检查重叠的规范
+3. 与变更所有者协调
+4. 考虑合并提案
+
+### 验证失败
+1. 使用 \`--strict\` 标志运行
+2. 检查 JSON 输出以获取详细信息
+3. 验证规范文件格式
+4. 确保场景格式正确
+
+### 缺少上下文
+1. 首先阅读 project.md
+2. 检查相关规范
+3. 审查最近的归档
+4. 请求澄清
+
+## 快速参考
+
+### 阶段指示器
+- \`changes/\` - 已提议，尚未构建
+- \`specs/\` - 已构建并部署
+- \`archive/\` - 已完成的变更
+
+### 文件用途
+- \`proposal.md\` - 原因和内容
+- \`tasks.md\` - 实施步骤
+- \`design.md\` - 技术决策
+- \`spec.md\` - 要求和行为
+
+### CLI 要点
+\`\`\`bash
+zhuanspec list              # 正在进行什么？
+zhuanspec show [item]       # 查看详细信息
+zhuanspec validate --strict # 是否正确？
+zhuanspec archive <change-id> [--yes|-y]  # 标记完成（添加 --yes 用于自动化）
+\`\`\`
+
+记住：规范是真相。变更是提案。保持它们同步。
+`;
+//# sourceMappingURL=agents-template.js.map