universal-dev-standards 5.14.0 → 5.16.0

package/bundled/locales/zh-CN/skills/ac-coverage/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ac-coverage
+source: ../../../../skills/ac-coverage/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: f8358fa818e4
+scope: universal
+status: current
+description: "[UDS] 分析验收条件（AC）与测试之间的追踪关系并生成覆盖率报告"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[规格文件路径]"
+---
+
+# AC 覆盖率助手
+
+> **语言**: [English](../../../../skills/ac-coverage/SKILL.md) | 简体中文
+
+分析验收条件（AC）与测试之间的追踪关系，并生成覆盖率报告。
+
+## 与 `/coverage` 的区别
+
+| 方面 | `/coverage` | `/ac-coverage` |
+|------|-------------|----------------|
+| **范围** | 代码层级（行数／分支／函数） | 需求层级（AC 对应测试） |
+| **输入** | 源代码 + 测试运行器 | SPEC 文件 + 测试标注 |
+| **问题** | 「代码测试了多少？」 | 「哪些 AC 有测试？」 |
+| **输出** | 覆盖率百分比 | 追踪矩阵 + 缺口报告 |
+
+## 工作流程
+
+1. **解析 SPEC** — 从规格文件中抽取 AC 定义（AC-1, AC-2, ...）
+2. **扫描测试** — 依标准链接约定搜索测试文件中的 `@AC` 与 `@SPEC` 标注
+3. **构建矩阵** — 将每个 AC 对应到其测试引用（文件、测试名称、行号）
+4. **分类状态** — 将每个 AC 标记为 ✅ 已覆盖、⚠️ 部分覆盖、或 ❌ 未覆盖
+5. **计算覆盖率** — 套用公式：`覆盖率 % = (已覆盖 + 部分覆盖 × 0.5) / 总数 × 100`
+6. **生成报告** — 输出标准化的 Markdown 报告
+
+## 链接标注约定
+
+测试**必须**使用标准标注引用其来源 AC：
+
+```typescript
+// TypeScript/JavaScript
+describe('AC-1: User login with valid credentials', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('should redirect to dashboard on successful login', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: User login with valid credentials
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+## 覆盖率门槛
+
+| 门槛 | 默认值 | 强制等级 |
+|------|--------|----------|
+| **签入（Check-in）** | 80% | feature branch 合并必要条件 |
+| **发布（Release）** | 100% | 生产环境发布必要条件 |
+| **警告（Warning）** | 60% | 触发覆盖率警告 |
+
+门槛可通过 `--threshold` 参数或项目配置文件调整。
+
+## 四层追溯（`--full` 模式）
+
+使用 `--full` 标记将追溯从 2 层（AC→Test）扩展为 4 层。
+
+### 追溯层次
+
+```
+Layer 0：需求 / 用户故事 (REQ)
+    ↓ （定义）
+Layer 1：验收条件 (AC)
+    ↓ （@AC 标注）
+Layer 2：测试用例
+    ↓ （覆盖）
+Layer 3：源代码 (@implements)
+```
+
+### 各层标注约定
+
+```typescript
+// Layer 3→1：代码引用 AC
+// @implements AC-1, AC-2
+function authenticate(user: string, pass: string) { ... }
+```
+
+```markdown
+<!-- Layer 0→1：SPEC 中的需求 -->
+## Requirements
+### REQ-1：用户验证
+- AC-1: 给定有效凭证，当登录时，则验证通过
+- AC-2: 给定无效凭证，当登录时，则被拒绝
+```
+
+### 完整追溯报告
+
+```markdown
+## 四层追溯矩阵
+
+| 需求 | AC | 测试 | 代码 | 状态 |
+|------|-----|------|------|------|
+| REQ-1 | AC-1 | auth.test.ts:15 | auth.ts:42 | ✅ 完整 |
+| REQ-1 | AC-2 | auth.test.ts:30 | auth.ts:58 | ✅ 完整 |
+| REQ-2 | AC-3 | — | dashboard.ts:10 | ⚠️ 缺测试 |
+| REQ-3 | AC-4 | export.test.ts:5 | — | ⚠️ 缺代码 |
+
+### 缺口摘要
+- Layer 0→1: 2 个需求未对应 AC
+- Layer 1→2: 1 个 AC 未对应测试
+- Layer 2→3: 0 个测试未对应代码
+- Layer 3→1: 3 个代码文件未对应 AC
+```
+
+### 反向追溯
+
+使用 `--trace-code <path>` 从代码反向追溯到需求。
+
+```bash
+/ac-coverage --trace-code src/auth.ts
+# 输出：
+# src/auth.ts:42 → @implements AC-1 → REQ-1 (SPEC-AUTH-001)
+# src/auth.ts:58 → @implements AC-2 → REQ-1 (SPEC-AUTH-001)
+```
+
+## 报告格式
+
+生成的报告遵循 `core/acceptance-criteria-traceability.md` 的标准格式：
+
+```markdown
+# AC 覆盖率报告
+
+**规格**: SPEC-001 — 功能名称
+**生成时间**: 2026-03-18
+**覆盖率**: 75% (6/8 AC)
+
+## 摘要
+
+| 状态 | 数量 | 百分比 |
+|------|------|--------|
+| ✅ 已覆盖 | 5 | 62.5% |
+| ⚠️ 部分覆盖 | 2 | 25.0% |
+| ❌ 未覆盖 | 1 | 12.5% |
+
+## 追溯矩阵
+
+| AC-ID | 描述 | 状态 | 测试引用 |
+|-------|------|------|----------|
+| AC-1 | 以有效凭证登录 | ✅ | auth.test.ts:15 |
+| AC-2 | 拒绝无效凭证 | ✅ | auth.test.ts:32 |
+| ...   | ...           | ... | ... |
+
+## 缺口
+- **AC-8**: 社交登录 — 因 OAuth sandbox 未就绪受阻
+
+## 行动项目
+1. [ ] AC-8：搭建 OAuth sandbox（预计时间：待定）
+```
+
+## 下一步引导
+
+`/ac-coverage` 完成后，AI 助手应建议：
+
+> **AC 覆盖率分析完成。建议下一步：**
+> - 覆盖率达标 → 执行 `/checkin` 质量关卡
+> - 有未覆盖 AC → 执行 `/derive-tdd` 补齐测试 ⭐ **推荐**
+> - 有部分覆盖 AC → 检查缺少的边界情况
+> - 需要完整追溯 → 执行 `/ac-coverage --full`
+> - 反向追溯 → 执行 `/ac-coverage --trace-code <path>`
+
+## 参考
+
+- 核心标准：[acceptance-criteria-traceability.md](../../../../core/acceptance-criteria-traceability.md)
+- SPEC：[SPEC-AC-COVERAGE.md](../../../../docs/specs/skills/SPEC-AC-COVERAGE.md)
+- 相关：[test-coverage-assistant](../test-coverage-assistant/SKILL.md)（代码层级覆盖率）
+- 相关：[checkin-assistant](../checkin-assistant/SKILL.md)（质量关卡）
+
+## AI 代理行为
+
+> 完整的 AI 行为定义请参阅对应的命令文件：[`/ac-coverage`](../../../../skills/commands/ac-coverage.md#ai-agent-behavior--ai-代理行为)

package/bundled/locales/zh-CN/skills/adr-assistant/SKILL.md

@@ -1,12 +1,13 @@
 ---
 source: ../../../../skills/adr-assistant/SKILL.md
 source_version: 1.0.0
+source_hash: 7d8bf5944cf4
 translation_version: 1.0.0
-last_synced: 2026-03-26
+last_synced: 2026-06-01
 status: current
 description: |
-  建立、管理和追踪架构决策记录（ADR）。
-  使用时机：架构决策、技术选型、设计取舍。
+  [UDS] 创建、管理和追踪架构决策记录（ADR）。
+  使用时机：架构决策、技术选型、设计取舍、模式选择。
   关键字：ADR, architecture decision, decision record, 架构决策, 决策记录。
 ---
 
@@ -14,7 +15,7 @@ description: |
 
 > **语言**: [English](../../../../skills/adr-assistant/SKILL.md) | 简体中文
 
-建立、管理和追踪架构决策记录。捕捉重大技术决策的背景、选项和理由。
+创建、管理和追踪架构决策记录。捕捉重大技术决策的背景、选项和理由。
 
 ## 工作流程
 
@@ -23,61 +24,155 @@ CAPTURE ──► ANALYZE ──► DECIDE ──► RECORD ──► LINK
   捕捉背景    分析选项    做出决策    记录 ADR    建立链接
 ```
 
+### 阶段 1：CAPTURE | 捕捉背景
+
+识别驱动决策的背景与约束条件。
+
+| 步骤 | 动作 |
+|------|------|
+| 1 | 识别问题或机会 |
+| 2 | 列出约束条件（时间、预算、团队技能） |
+| 3 | 定义决策驱动因素 |
+
+### 阶段 2：ANALYZE | 分析选项
+
+至少探索 2 个选项，列出优缺点。
+
+| 步骤 | 动作 |
+|------|------|
+| 1 | 头脑风暴候选方案 |
+| 2 | 根据决策驱动因素评估各方案 |
+| 3 | 记录各方案优缺点 |
+
+### 阶段 3：DECIDE | 做出决策
+
+选择最佳方案并阐述理由。
+
+### 阶段 4：RECORD | 记录 ADR
+
+依照标准模板生成 ADR 文件。
+
+### 阶段 5：LINK | 建立链接
+
+与相关工件（规格、PR、代码）建立交叉引用。
+
+## 快速参考
+
+### 何时撰写 ADR
+
+| 撰写 ADR | 不需要 ADR |
+|----------|-----------|
+| 框架/库选择 | 例行性依赖更新 |
+| API 合约或数据格式 | 现有架构内的 Bug 修复 |
+| 部署策略变更 | 代码风格决策 |
+| 建立新模式 | 琐碎的实现选择 |
+
+**经验法则**：如果 6 个月后有人可能会问「为什么？」，就写一份 ADR。
+
+### 状态生命周期
+
+```
+Proposed ──► Accepted ──► Deprecated
+                │
+                └──► Superseded by ADR-NNN
+```
+
+| 状态 | 说明 |
+|------|------|
+| **Proposed** | 讨论中，尚未决定 |
+| **Accepted** | 已接受，应遵循 |
+| **Deprecated** | 不再适用 |
+| **Superseded** | 已被新 ADR 取代 |
+
+### 模板摘要
+
+```markdown
+# ADR-NNN: [决策标题]
+
+- Status: [Proposed | Accepted | Deprecated | Superseded]
+- Date: YYYY-MM-DD
+- Deciders: [参与决策者]
+- Technical Story: [SPEC-ID 或 Issue]
+
+## Context（背景）
+## Decision Drivers（决策驱动因素）
+## Considered Options（考虑的选项）
+## Decision Outcome（决策结果）
+### Consequences（后果：Good / Bad / Neutral）
+## Links（相关链接）
+```
+
+### 存放位置
+
+```
+docs/adr/
+├── ADR-001-short-description.md
+├── ADR-002-short-description.md
+└── README.md    # 索引（可选）
+```
+
 ## 指令
 
 | 指令 | 说明 |
 |------|------|
-| `/adr` | 交互式建立 ADR |
-| `/adr create` | 建立新 ADR |
+| `/adr` | 交互式创建 ADR |
+| `/adr create` | 创建新 ADR |
 | `/adr list` | 列出所有 ADR 及状态 |
 | `/adr search [关键字]` | 依关键字搜索 ADR |
 | `/adr supersede [ADR-NNN]` | 取代现有 ADR |
 | `/adr review` | 审查过期的 ADR |
 
-## 参考
+## 与其他技能的集成
 
-- 核心规范：[adr-standards.md](../../../../core/adr-standards.md)
-- 详细指南：[guide.md](./guide.md)
+| 技能 | 集成方式 |
+|------|---------|
+| `/sdd` | 在技术设计中引用 ADR；重大决策时建议创建 ADR |
+| `/review` | 代码审查时引用 ADR 作为设计依据 |
+| `/commit` | 提交时在 footer 加入 ADR 编号 |
+| `/brainstorm` | 头脑风暴结果作为 ADR 选项分析输入 |
 
+## 质量检查清单
 
-## Next Steps Guidance | 下一步引導
+| 检查项 | 标准 |
+|--------|------|
+| ☐ 背景 | 清楚说明问题 |
+| ☐ 选项 | 至少考虑 2 个选项 |
+| ☐ 驱动因素 | 决策驱动因素明确列出 |
+| ☐ 后果 | 包含正面与负面结果 |
+| ☐ 链接 | 相关工件已引用 |
 
-After `/adr` completes, the AI assistant should suggest:
+## 下一步引导
 
-> **ADR created. Suggested next steps:**
-> - Execute `/sdd` to create a spec if the decision requires implementation
-> - Execute `/commit` to commit the ADR file
-> - Update related SPECs to reference this ADR
-> - Share with team for review if status is `Proposed`
+`/adr` 完成后，AI 助手应建议：
 
-> **ADR 已建立。建議下一步：**
-> - 執行 `/sdd` 建立規格（若決策需要實作）
-> - 執行 `/commit` 提交 ADR 檔案
-> - 更新相關規格以引用此 ADR
-> - 若狀態為 `Proposed`，分享給團隊審查
+> **ADR 已创建。建议下一步：**
+> - 执行 `/sdd` 创建规格（若决策需要实现）
+> - 执行 `/commit` 提交 ADR 文件
+> - 更新相关规格以引用此 ADR
+> - 若状态为 `Proposed`，分享给团队审查
 
-## AI Agent Behavior | AI 代理行為
+## AI 代理行为
 
-When the user invokes `/adr`, the AI assistant MUST:
+当用户调用 `/adr` 时，AI 助手必须：
 
-1. **Check existing ADRs** — Search `docs/adr/` to determine next ADR number
-2. **Guide interactively** — Ask about context, drivers, and options step by step
-3. **Generate the file** — Write ADR to `docs/adr/ADR-NNN-title.md`
-4. **Suggest links** — Identify related SPECs or ADRs to cross-reference
-5. **Offer next steps** — Show the Next Steps Guidance above
+1. **检查现有 ADR** — 搜索 `docs/adr/` 以确定下一个 ADR 编号
+2. **交互式引导** — 逐步询问背景、驱动因素和选项
+3. **生成文件** — 将 ADR 写入 `docs/adr/ADR-NNN-title.md`
+4. **建议链接** — 识别相关规格或 ADR 以建立交叉引用
+5. **提供下一步** — 显示上方的下一步引导
 
-When the user invokes `/adr list`:
-1. Scan `docs/adr/` directory
-2. Parse status from each ADR file
-3. Display as a table: Number, Title, Status, Date
+当用户调用 `/adr list` 时：
+1. 扫描 `docs/adr/` 目录
+2. 解析每个 ADR 文件的状态
+3. 以表格显示：编号、标题、状态、日期
 
-When the user invokes `/adr supersede [ADR-NNN]`:
-1. Read the existing ADR
-2. Guide creation of a new ADR
-3. Update old ADR status to `Superseded by ADR-NNN`
-4. Add `Supersedes ADR-NNN` to new ADR
+当用户调用 `/adr supersede [ADR-NNN]` 时：
+1. 读取现有 ADR
+2. 引导创建新 ADR
+3. 将旧 ADR 状态更新为 `Superseded by ADR-NNN`
+4. 在新 ADR 中加入 `Supersedes ADR-NNN`
 
-## Reference | 參考
+## 参考
 
-- Core Standard: [adr-standards.md](../../core/adr-standards.md)
-- Detailed Guide: [guide.md](./guide.md)
+- 核心规范：[adr-standards.md](../../../../core/adr-standards.md)
+- 详细指南：[guide.md](./guide.md)