universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-CN/integrations/opencode/skills-mapping.md

@@ -0,0 +1,396 @@
+---
+source: ../../../../integrations/opencode/skills-mapping.md
+source_version: 1.4.0
+translation_version: 1.4.0
+last_synced: 2026-01-13
+status: current
+---
+
+# Skills 移植指南
+
+本文档将 Claude Code 技能对应到 OpenCode 的等效实现方式。
+
+---
+
+## 概述
+
+Claude Code 提供 18 个技能和 16 个斜线命令。OpenCode 原生支持技能，且**完全兼容** Claude Code 技能格式。
+
+### 关键优势：原生兼容
+
+OpenCode 按以下顺序搜索技能：
+1. `.opencode/skill/<name>/SKILL.md`（项目本地）
+2. `~/.config/opencode/skill/<name>/SKILL.md`（全局）
+3. **`.claude/skills/<name>/SKILL.md`**（Claude 兼容 ✅）
+
+这意味着所有 UDS Claude Code 技能无需修改即可在 OpenCode 中使用。
+
+---
+
+## 技能对照表
+
+| Claude Code 技能 | OpenCode 实现方式 | 状态 |
+|-----------------|-------------------|------|
+| **ai-collaboration-standards** | AGENTS.md 第 2 节 | ✅ 完整 |
+| **commit-standards** | AGENTS.md 第 3 节 + 技能 | ✅ 完整 |
+| **code-review-assistant** | AGENTS.md 第 4 节 + 技能 | ✅ 完整 |
+| **tdd-assistant** | 技能（自动加载） | ✅ 完整 |
+| **test-coverage-assistant** | 技能（自动加载） | ✅ 完整 |
+| **checkin-assistant** | AGENTS.md 第 5 节 + 技能 | ✅ 完整 |
+| **requirement-assistant** | 技能（自动加载） | ✅ 完整 |
+| **spec-driven-dev** | AGENTS.md 第 1 节 + 技能 | ✅ 完整 |
+| **testing-guide** | 技能（自动加载） | ✅ 完整 |
+| **release-standards** | 技能（自动加载） | ✅ 完整 |
+| **changelog-guide** | 技能（自动加载） | ✅ 完整 |
+| **git-workflow-guide** | 技能（自动加载） | ✅ 完整 |
+| **documentation-guide** | 技能（自动加载） | ✅ 完整 |
+| **methodology-system** | 技能（自动加载） | ✅ 完整 |
+| **refactoring-assistant** | 技能（自动加载） | ✅ 完整 |
+| **error-code-guide** | 技能（自动加载） | ✅ 完整 |
+| **project-structure-guide** | 技能（自动加载） | ✅ 完整 |
+| **logging-guide** | 技能（自动加载） | ✅ 完整 |
+
+### 状态说明
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 完整 | 技能在 OpenCode 中完全相同 |
+| ⚠️ 部分 | 部分功能有差异 |
+| ❌ 无 | 无法复制 |
+
+---
+
+## 斜线命令对照
+
+OpenCode 支持与 Claude Code 相同的技能调用语法：
+
+| Claude Code | OpenCode | 备注 |
+|-------------|----------|------|
+| `/commit` | `/commit` 或 `skill("commit-standards")` | 相同 |
+| `/review` | `/review` 或 `skill("code-review-assistant")` | 相同 |
+| `/tdd` | `/tdd` 或 `skill("tdd-assistant")` | 相同 |
+| `/coverage` | `/coverage` 或 `skill("test-coverage-assistant")` | 相同 |
+| `/requirement` | `/requirement` 或 `skill("requirement-assistant")` | 相同 |
+| `/check` | `/check` 或 `skill("checkin-assistant")` | 相同 |
+| `/release` | `/release` 或 `skill("release-standards")` | 相同 |
+| `/changelog` | `/changelog` 或 `skill("changelog-guide")` | 相同 |
+| `/docs` | `/docs` 或 `skill("documentation-guide")` | 相同 |
+| `/spec` | `/spec` 或 `skill("spec-driven-dev")` | 相同 |
+| `/methodology` | `/methodology` 或 `skill("methodology-system")` | 相同 |
+| `/bdd` | 通过 `/methodology` 或 `/tdd` | 相同功能 |
+| `/config` | `/config` 或 `skill("project-structure-guide")` | 相同 |
+| `/init` | `/init`（内置） | OpenCode 原生 |
+| `/update` | 手动或通过 CLI | 使用 `uds update` |
+
+---
+
+## 安装方法
+
+### 方法一：使用 UDS CLI（推荐）
+
+为 Claude Code 和 OpenCode 获取技能的最简单方式：
+
+```bash
+# 全局安装 UDS CLI
+npm install -g universal-dev-standards
+
+# 初始化项目 - 选择 OpenCode 作为 AI 工具
+uds init
+
+# 技能会安装到 .claude/skills/
+# OpenCode 会自动检测此路径 ✅
+```
+
+**v3.5.0 新功能**：OpenCode 现在在 CLI 中被视为 skills 兼容工具。
+当只选择 OpenCode（或 Claude Code）时，将自动提供带有 skills 的精简安装。
+
+```bash
+# 验证安装状态和 skills 兼容性
+uds check
+```
+
+### 方法二：从 GitHub 克隆
+
+```bash
+# 克隆仓库
+git clone https://github.com/AsiaOstrich/universal-dev-standards.git /tmp/uds
+
+# 复制技能到 OpenCode 目录
+cp -r /tmp/uds/skills/claude-code/* ~/.config/opencode/skill/
+
+# 或复制到项目级别
+cp -r /tmp/uds/skills/claude-code/* .opencode/skill/
+
+# 清理
+rm -rf /tmp/uds
+```
+
+### 方法三：通过 Claude Code Plugin（若已安装）
+
+如果您已通过 Claude Code Plugin Marketplace 安装 UDS：
+
+```bash
+# 检查技能安装位置
+uds skills
+
+# 从 Claude 技能路径复制到 OpenCode
+cp -r .claude/skills/* ~/.config/opencode/skill/
+
+# 或复制特定技能
+cp -r .claude/skills/commit-standards ~/.config/opencode/skill/
+```
+
+### 方法四：直接下载
+
+```bash
+# 直接下载特定技能
+mkdir -p .opencode/skill/commit-standards
+curl -o .opencode/skill/commit-standards/SKILL.md \
+  https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills/claude-code/commit-standards/SKILL.md
+```
+
+### 方法五：使用 Claude 路径（零配置）
+
+如果您已通过 `uds init` 安装 Claude Code 技能：
+
+```bash
+# OpenCode 会自动检测 .claude/skills/
+# 无需任何操作！
+```
+
+### 方法六：社区 Marketplace
+
+OpenCode 没有像 Claude Code 那样的官方 marketplace，但有几个社区驱动的选项：
+
+**[n-skills](https://github.com/numman-ali/n-skills)** - 精选 marketplace：
+- 支持 Claude Code、Cursor、Windsurf、Cline、OpenCode 和 Codex
+- 只收录高质量、有实际价值的技能
+
+**[claude-plugins.dev](https://claude-plugins.dev/skills)** - 自动索引发现：
+- 自动索引 GitHub 上所有公开的 Agent Skills
+- 支持 Claude、Cursor、OpenCode、Codex 等 AI 编码助手
+
+**[agentskills.io](https://agentskills.io)** - 开放标准：
+- Anthropic 于 2024 年 12 月发布的 Agent Skills 规范
+- 已被 OpenCode、Codex、Cursor 等多种工具采用
+
+---
+
+## 功能比较
+
+### 相同功能
+
+| 功能 | Claude Code | OpenCode |
+|------|-------------|----------|
+| 技能格式 | YAML frontmatter + Markdown | ✅ 相同 |
+| 技能搜索路径 | `.claude/skills/` | ✅ + `.opencode/skill/` |
+| 斜线命令 | `/commit`、`/review` 等 | ✅ 相同 |
+| 自动触发 | 基于关键字 | ✅ 相同 |
+| 技能权限 | 按技能设置 | ✅ 相同 |
+
+### OpenCode 优势
+
+| 功能 | Claude Code | OpenCode |
+|------|-------------|----------|
+| 内置 agents | ❌ 无 | ✅ `build`、`plan`、`general`、`explore` |
+| Agent 定义 | ❌ 非原生 | ✅ Markdown 文件 |
+| Glob 模式 | ❌ 不支持 | ✅ `instructions: ["**/*.md"]` |
+| Subagent 调用 | ❌ 非原生 | ✅ `@agent-name` |
+| 多 LLM 提供者 | ❌ 仅 Claude | ✅ Claude、OpenAI、Google、本地 |
+
+### Claude Code 优势
+
+| 功能 | Claude Code | OpenCode |
+|------|-------------|----------|
+| MCP 集成 | ✅ 完整 | ⚠️ 有限 |
+| 子目录规则 | ✅ 每文件夹 CLAUDE.md | ❌ 单一 AGENTS.md |
+| 工具生态系 | ✅ Anthropic 工具 | ⚠️ 社区工具 |
+
+---
+
+## 跨工具兼容性
+
+### Skills 路径参考
+
+[Agent Skills 规范](https://agentskills.io/specification) **未指定标准安装路径**，各工具自行实现探索机制。
+
+#### 路径对照表
+
+| AI Agent | 项目路径 | 用户路径 | Claude 兼容 |
+|----------|---------|---------|-------------|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | ✅ 原生 |
+| OpenCode | `.opencode/skill/`<br>`.claude/skills/` | `~/.config/opencode/skill/` | ✅ 支持 |
+| Cursor | `.cursor/skills/`<br>`.claude/skills/` | `~/.cursor/skills/`<br>`~/.claude/skills/` | ✅ 支持 |
+| OpenAI Codex | `.codex/skills/` | `~/.codex/skills/` | ❌ 独立 |
+| GitHub Copilot | `.github/skills/`<br>`.claude/skills/` (legacy) | `~/.copilot/skills/`<br>`~/.claude/skills/` (legacy) | ✅ 支持 |
+| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | ❌ 独立 |
+| Cline | `.cline/skills/` | `~/.cline/skills/` | ❌ 独立 |
+
+#### 为何选择 `.claude/skills/`？
+
+UDS 将技能安装到 `.claude/skills/` 的原因：
+
+1. **最广泛兼容**：多数工具支持此路径（Cursor、Copilot、OpenCode）
+2. **事实标准**：Claude Code 是 Agent Skills 概念的发起者
+3. **单次安装**：一次安装即可跨多个工具使用
+
+#### 未来考量
+
+- GitHub Copilot 建议使用 `.github/skills/`（将 `.claude/` 标记为 legacy）
+- 中立路径如 `.agent-skills/` 可能成为未来标准
+- UDS 将在社区达成共识时进行调整
+
+#### 跨工具安装
+
+对于不读取 `.claude/skills/` 的工具：
+
+| 工具 | 解决方案 |
+|------|----------|
+| OpenAI Codex | `cp -r .claude/skills/* ~/.codex/skills/` |
+| Windsurf | `cp -r .claude/skills/* .windsurf/skills/` |
+| Cline | `cp -r .claude/skills/* .cline/skills/` |
+
+---
+
+## 技能专用自定义 Agents
+
+OpenCode 允许为特定技能创建专门的 agent：
+
+### 代码审查 Agent
+
+```markdown
+<!-- .opencode/agent/reviewer.md -->
+---
+description: 依据 UDS 代码审查清单进行审查
+mode: subagent
+temperature: 0.3
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+# 代码审查 Agent
+
+您是代码审查专家。请遵循以下指南：
+
+1. 使用 code-review-assistant 技能
+2. 应用 core/code-review-checklist.md 的审查清单
+3. 使用注释前缀：❗ BLOCKING、⚠️ IMPORTANT、💡 SUGGESTION、❓ QUESTION
+4. 检查所有 10 个审查类别
+
+调用方式：@reviewer
+```
+
+### TDD 教练 Agent
+
+```markdown
+<!-- .opencode/agent/tdd-coach.md -->
+---
+description: 引导 TDD 工作流程（红-绿-重构）
+mode: subagent
+temperature: 0.5
+---
+
+# TDD 教练 Agent
+
+您是 TDD 教练。协助开发者：
+
+1. 红色阶段：编写失败的测试
+2. 绿色阶段：最少代码通过测试
+3. 重构阶段：保持绿色下清理代码
+
+始终使用 tdd-assistant 技能。
+
+调用方式：@tdd-coach
+```
+
+---
+
+## 技能配置
+
+### 权限控制
+
+```json
+// opencode.json
+{
+  "permission": {
+    "skill": {
+      "*": "allow",
+      "methodology-system": "ask",
+      "release-standards": "ask"
+    }
+  }
+}
+```
+
+### 停用特定技能
+
+```json
+// opencode.json
+{
+  "permission": {
+    "skill": {
+      "methodology-system": "deny"
+    }
+  }
+}
+```
+
+---
+
+## 验证清单
+
+设置技能后：
+
+```
+□ 运行 `opencode` 并输入 `/commit` 测试技能加载
+□ 验证技能自动完成功能（输入 `/` 查看可用项目）
+□ 使用 `@agent-name` 测试自定义 agents
+□ 确认 AGENTS.md 已加载（使用 `/show rules` 查看）
+□ 确认 glob 模式工作（若在 opencode.json 中使用）
+```
+
+---
+
+## 疑难排解
+
+### 技能未加载
+
+1. **检查文件名称**：必须是 `SKILL.md`（全大写）
+2. **验证 frontmatter**：需要 `name` 和 `description`
+3. **检查路径**：应为 `.opencode/skill/<name>/SKILL.md`
+4. **查看权限**：检查 `opencode.json` 技能权限
+
+### 斜线命令无效
+
+1. **验证技能存在**：检查技能目录
+2. **检查名称对应**：斜线命令使用技能的 `name` 字段
+3. **尝试完整语法**：使用 `skill("skill-name")` 而非 `/skill-name`
+
+---
+
+## 相关资源
+
+- [AGENTS.md](../../../../integrations/opencode/AGENTS.md) - 核心规则文件
+- [opencode.json](../../../../integrations/opencode/opencode.json) - 配置示例
+- [Claude Code Skills](../../../../skills/claude-code/) - 原始技能
+- [GitHub Copilot 技能对照](../github-copilot/skills-mapping.md) - Copilot 等效版本
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.4.0 | 2026-01-13 | 新增跨工具兼容性章节与路径对照表 |
+| 1.3.0 | 2026-01-13 | 新增社区 marketplace 章节（n-skills、claude-plugins.dev、agentskills.io） |
+| 1.2.0 | 2026-01-13 | 更新 CLI 方法；OpenCode 现在在 UDS CLI 中支持 skills |
+| 1.1.0 | 2026-01-13 | 修正安装方法；移除错误的 npm 路径 |
+| 1.0.0 | 2026-01-13 | 初始版本 |
+
+---
+
+## 许可证
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。

package/bundled/locales/zh-CN/integrations/openspec/AGENTS.md

@@ -0,0 +1,301 @@
+---
+source: ../../../../integrations/openspec/AGENTS.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-01-13
+status: current
+---
+
+# OpenSpec 指令
+
+使用 OpenSpec 进行规格驱动开发的 AI 编码助手指令。
+
+## 快速检查清单
+
+- 搜索现有工作：`openspec spec list --long`、`openspec list`（仅使用 `rg` 进行全文搜索）
+- 决定范围：新功能 vs 修改现有功能
+- 选择唯一的 `change-id`：kebab-case，动词开头（`add-`、`update-`、`remove-`、`refactor-`）
+- 创建骨架：`proposal.md`、`tasks.md`、`design.md`（仅在需要时），以及每个受影响功能的差异规格
+- 撰写差异：使用 `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`；每个需求至少包含一个 `#### Scenario:`
+- 验证：`openspec validate [change-id] --strict` 并修复问题
+- 请求核准：在提案核准前不要开始实现
+
+## 三阶段工作流程
+
+### 阶段 1：创建变更
+在需要以下情况时创建提案：
+- 新增功能或特性
+- 进行破坏性变更（API、schema）
+- 变更架构或模式
+- 性能优化（改变行为）
+- 更新安全模式
+
+触发条件（示例）：
+- 「帮我创建变更提案」
+- 「帮我规划变更」
+- 「帮我创建提案」
+- 「我想创建规格提案」
+- 「我想创建规格」
+
+可跳过提案的情况：
+- 错误修复（恢复预期行为）
+- 错字、格式、注释
+- 依赖更新（非破坏性）
+- 配置变更
+- 现有行为的测试
+
+**工作流程**
+1. 审查 `openspec/project.md`、`openspec list` 和 `openspec list --specs` 以了解当前上下文。
+2. 选择唯一的动词开头 `change-id`，在 `openspec/changes/<id>/` 下创建 `proposal.md`、`tasks.md`、可选的 `design.md` 和规格差异。
+3. 使用 `## ADDED|MODIFIED|REMOVED Requirements` 草拟规格差异，每个需求至少有一个 `#### Scenario:`。
+4. 执行 `openspec validate <id> --strict` 并在分享提案前解决所有问题。
+
+### 阶段 2：实现变更
+将这些步骤作为待办事项追踪，逐一完成。
+1. **阅读 proposal.md** - 了解正在构建什么
+2. **阅读 design.md**（如存在）- 审查技术决策
+3. **阅读 tasks.md** - 获取实现检查清单
+4. **依序实现任务** - 按顺序完成
+5. **确认完成** - 确保 `tasks.md` 中每个项目完成后才更新状态
+6. **更新检查清单** - 所有工作完成后，将每个任务设为 `- [x]` 以反映实际状态
+7. **核准关卡** - 在提案审查和核准前不要开始实现
+
+### 阶段 3：归档变更
+部署后，创建单独的 PR：
+- 将 `changes/[name]/` 移至 `changes/archive/YYYY-MM-DD-[name]/`
+- 如功能有变更则更新 `specs/`
+- 对于纯工具类变更使用 `openspec archive <change-id> --skip-specs --yes`（始终明确传递 change ID）
+- 执行 `openspec validate --strict` 确认归档的变更通过检查
+
+## 任何任务之前
+
+**上下文检查清单：**
+- [ ] 阅读 `specs/[capability]/spec.md` 中的相关规格
+- [ ] 检查 `changes/` 中是否有冲突的待处理变更
+- [ ] 阅读 `openspec/project.md` 了解惯例
+- [ ] 执行 `openspec list` 查看活跃变更
+- [ ] 执行 `openspec list --specs` 查看现有功能
+
+**创建规格前：**
+- 始终检查功能是否已存在
+- 优先修改现有规格而非创建重复项
+- 使用 `openspec show [spec]` 审查当前状态
+- 如请求模糊，在创建骨架前询问 1-2 个澄清问题
+
+### 搜索指引
+- 列举规格：`openspec spec list --long`（或 `--json` 用于脚本）
+- 列举变更：`openspec list`（或 `openspec change list --json` - 已弃用但可用）
+- 显示详情：
+  - 规格：`openspec show <spec-id> --type spec`（使用 `--json` 进行过滤）
+  - 变更：`openspec show <change-id> --json --deltas-only`
+- 全文搜索（使用 ripgrep）：`rg -n "Requirement:|Scenario:" openspec/specs`
+
+## 快速开始
+
+### CLI 指令
+
+```bash
+# 基本指令
+openspec list                  # 列出活跃变更
+openspec list --specs          # 列出规格
+openspec show [item]           # 显示变更或规格
+openspec validate [item]       # 验证变更或规格
+openspec archive <change-id> [--yes|-y]   # 部署后归档（添加 --yes 用于非交互执行）
+
+# 项目管理
+openspec init [path]           # 初始化 OpenSpec
+openspec update [path]         # 更新指令文件
+
+# 交互模式
+openspec show                  # 提示选择
+openspec validate              # 批量验证模式
+
+# 调试
+openspec show [change] --json --deltas-only
+openspec validate [change] --strict
+```
+
+### 指令标志
+
+- `--json` - 机器可读输出
+- `--type change|spec` - 区分项目
+- `--strict` - 全面验证
+- `--no-interactive` - 禁用提示
+- `--skip-specs` - 归档时不更新规格
+- `--yes`/`-y` - 跳过确认提示（非交互归档）
+
+## 目录结构
+
+```
+openspec/
+├── 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/            # 已完成变更
+```
+
+## 创建变更提案
+
+### 决策树
+
+```
+新请求？
+├─ 恢复规格行为的错误修复？ → 直接修复
+├─ 错字/格式/注释？ → 直接修复
+├─ 新功能/特性？ → 创建提案
+├─ 破坏性变更？ → 创建提案
+├─ 架构变更？ → 创建提案
+└─ 不确定？ → 创建提案（较安全）
+```
+
+### 提案结构
+
+1. **创建目录：** `changes/[change-id]/`（kebab-case，动词开头，唯一）
+
+2. **撰写 proposal.md：**
+```markdown
+# 变更：[变更简述]
+
+## 为何
+[1-2 句说明问题/机会]
+
+## 变更内容
+- [变更项目列表]
+- [以 **BREAKING** 标记破坏性变更]
+
+## 影响
+- 受影响规格：[列出功能]
+- 受影响代码：[关键文件/系统]
+```
+
+3. **创建规格差异：** `specs/[capability]/spec.md`
+```markdown
+## ADDED Requirements
+### Requirement: 新功能
+系统应提供...
+
+#### Scenario: 成功案例
+- **WHEN** 用户执行动作
+- **THEN** 预期结果
+
+## MODIFIED Requirements
+### Requirement: 现有功能
+[完整的修改后需求]
+
+## REMOVED Requirements
+### Requirement: 旧功能
+**原因**：[移除原因]
+**迁移**：[如何处理]
+```
+如果多个功能受影响，在 `changes/[change-id]/specs/<capability>/spec.md` 下创建多个差异文件——每个功能一个。
+
+4. **创建 tasks.md：**
+```markdown
+## 1. 实现
+- [ ] 1.1 创建数据库 schema
+- [ ] 1.2 实现 API 端点
+- [ ] 1.3 添加前端组件
+- [ ] 1.4 编写测试
+```
+
+5. **在需要时创建 design.md：**
+如符合以下任一条件则创建 `design.md`；否则省略：
+- 跨模块变更（多个服务/模块）或新架构模式
+- 新外部依赖或重大数据模型变更
+- 安全、性能或迁移复杂度
+- 在编码前需要技术决策来消除歧义
+
+## 规格文件格式
+
+### 重要：场景格式
+
+**正确**（使用 #### 标题）：
+```markdown
+#### Scenario: 用户登录成功
+- **WHEN** 提供有效凭证
+- **THEN** 返回 JWT token
+```
+
+**错误**（不要使用项目符号或粗体）：
+```markdown
+- **Scenario: 用户登录**  ❌
+**Scenario**: 用户登录     ❌
+### Scenario: 用户登录      ❌
+```
+
+每个需求必须至少有一个场景。
+
+### 需求用语
+- 使用 SHALL/MUST 表示规范性需求（除非刻意为非规范性，否则避免 should/may）
+
+### 差异操作
+
+- `## ADDED Requirements` - 新功能
+- `## MODIFIED Requirements` - 行为变更
+- `## REMOVED Requirements` - 弃用功能
+- `## RENAMED Requirements` - 名称变更
+
+标题以 `trim(header)` 匹配 - 忽略空白。
+
+## 最佳实践
+
+### 简单优先
+- 默认为 <100 行新代码
+- 单文件实现直到证明不足
+- 无明确理由不使用框架
+- 选择无聊、经过验证的模式
+
+### 复杂度触发条件
+仅在以下情况增加复杂度：
+- 性能数据显示当前解决方案过慢
+- 具体的规模需求（>1000 用户、>100MB 数据）
+- 需要抽象的多个已验证用例
+
+### 清晰引用
+- 使用 `file.ts:42` 格式标示代码位置
+- 以 `specs/auth/spec.md` 格式引用规格
+- 链接相关变更和 PR
+
+### 功能命名
+- 使用动词-名词：`user-auth`、`payment-capture`
+- 每个功能单一目的
+- 10 分钟可理解规则
+- 如描述需要「和」则拆分
+
+### 变更 ID 命名
+- 使用 kebab-case，简短且描述性：`add-two-factor-auth`
+- 优先使用动词开头前缀：`add-`、`update-`、`remove-`、`refactor-`
+- 确保唯一性；若已被使用，附加 `-2`、`-3` 等
+
+## 快速参考
+
+### 阶段指示
+- `changes/` - 提议，尚未构建
+- `specs/` - 已构建和部署
+- `archive/` - 已完成变更
+
+### 文件用途
+- `proposal.md` - 为何和什么
+- `tasks.md` - 实现步骤
+- `design.md` - 技术决策
+- `spec.md` - 需求和行为
+
+### CLI 基本指令
+```bash
+openspec list              # 正在进行什么？
+openspec show [item]       # 查看详情
+openspec validate --strict # 是否正确？
+openspec archive <change-id> [--yes|-y]  # 标记完成（添加 --yes 用于自动化）
+```
+
+记住：规格是真相。变更是提案。保持同步。