@haaaiawd/anws 1.2.5 → 2.0.0

package/templates/.agents/skills/report-template/references/REPORT_TEMPLATE.md

@@ -0,0 +1,100 @@
+# 系统上下文报告
+
+**生成日期**: {{DATE}}
+**分析目标**: {{SCOPE}}
+
+## 执行摘要
+> [用一句话总结系统当前状态，例如：“一个总体稳健的 Python 后端，但 Auth 模块存在一定技术债。”]
+
+---
+
+## 1. 组件清单
+
+### 1.1 现有组件
+| 组件 | 类型 | 路径 | 描述 |
+|---|---|---|---|
+| [名称] | [Service/UI/DB] | [路径] | [简要描述] |
+
+### 1.2 缺失组件（暗物质）
+> [!WARNING]
+> 以下组件当前缺失，但对生产可用性至关重要。
+
+| 组件 | 类别 | 为什么需要 | 缺失影响 |
+|---|---|---|---|
+| 错误处理 | 基础设施 | 未发现统一错误边界 | 调试将非常困难 |
+| 日志 | 可观测性 | 缺少结构化日志 | 线上将失明 |
+| 配置管理 | 运维 | 检测到硬编码密钥 | 安全风险 |
+
+---
+
+## 2. 依赖拓扑
+
+### 2.1 构建边界（Build Inspector）
+> [插入来自 `build-inspector` 的发现：Build Roots、Topology、Sidecar Warnings]
+
+```mermaid
+graph TD
+    A[模块 A] --> B[模块 B]
+```
+
+### 2.2 逻辑耦合（Git Forensics）
+> [插入热点矩阵或耦合表]
+
+| 文件 A | 文件 B | 耦合度 | 风险 |
+|---|---|---|---|
+| auth.py | user_db.py | 85% | HIGH |
+
+---
+
+## 3. 风险与警告
+
+### 3.1 IPC 契约风险（Runtime Inspector）
+> [!CAUTION]
+> [列出由 `runtime-inspector` 发现的 IPC 接口中契约薄弱或缺失的部分]
+
+### 3.2 上帝模块
+> [列出 Ca（传入耦合）过高的模块]
+
+### 3.3 技术债热点
+> [列出高变更频率 + 高复杂度的文件]
+
+---
+
+## 4. 隐式约束（Invariant Hunter）
+
+### 4.1 业务不变量
+> [永远不能被破坏的规则]
+- 订单总额必须 >= 0
+- 用户在支付前必须完成邮箱验证
+
+### 4.2 假设
+> [代码中存在但未被显式声明的假设]
+- “网络总是可靠的”（没有重试逻辑）
+- “ID 永远是整数”
+
+### 4.3 硬编码值
+- API 密钥
+- 超时值
+
+---
+
+## 5. 概念模型（Concept Modeler）
+
+### 5.1 统一语言
+| 术语 | 定义 |
+|---|---|
+| 用户 | 已注册的终端用户（不是管理员） |
+| 订单 | 一次购买请求 |
+
+### 5.2 数据流
+> [描述关键流程]
+
+---
+
+## 6. 人类检查点
+> [!IMPORTANT]
+> 在进入 Blueprint 阶段前，请确认以下事项：
+
+- [ ] 组件清单是否完整？
+- [ ] 当前识别出的风险是否可接受？
+- [ ] 所有不变量是否都已捕获？

package/templates/{.agent → .agents}/skills/runtime-inspector/SKILL.md

@@ -16,7 +16,7 @@ description: 分析运行时行为、进程边界和 IPC 机制，检测"协议
 ## ⚠️ 强制深度思考
 
 > [!IMPORTANT]
-> 在执行任何分析之前，你**必须**调用 `sequential thinking` 工具，视情况进行 **3—5 步**推理。
+> 在执行任何分析之前，你**必须**使用 `sequential-thinking` skill，视情况组织 **3—5 个 thought** 推理。
 > 思考内容例如：
 > 1.  "这个项目有多少个入口点（`main` 函数）？它们是一个进程还是多个？"
 > 2.  "进程之间用什么通信？Pipe？HTTP？共享数据库？"

package/templates/.agents/skills/sequential-thinking/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: sequential-thinking
+description: 当复杂问题需要系统性逐步推理时使用。适用于多阶段分析、设计规划、问题分解，或初始范围不明确且可能需要修正、分支与动态调整思考范围的任务。
+license: MIT
+---
+
+# Sequential Thinking
+
+通过可修正、可分支、可动态扩展的顺序推理，帮助 AI 处理复杂问题。
+
+## Core Capabilities
+
+- **迭代推理**: 将复杂问题拆解为连续的 thought 步骤
+- **动态范围**: 随着理解深入调整 `totalThoughts`
+- **修正能力**: 当新证据出现时回看并修正早期判断
+- **分支探索**: 从关键分叉点探索替代路径
+- **上下文保持**: 在整个推理过程中维持清晰的思考链条
+
+## When to Use
+
+在以下场景使用：
+- 问题需要多个相互关联的推理步骤
+- 初始范围或方法不明确
+- 需要在复杂性中找到核心问题
+- 可能需要回溯或修正早期结论
+- 想探索替代方案路径
+
+**不适用场景**: 简单查询、直接事实、单步任务，或解决路径已经非常明确的问题。
+
+## Basic Usage
+
+按如下 JSON 形态组织思考步骤。
+
+### Required Fields
+
+- `thought` (string): 当前推理内容
+- `nextThoughtNeeded` (boolean): 是否还需要继续推理
+- `thoughtNumber` (integer): 当前 thought 编号，从 `1` 开始
+- `totalThoughts` (integer): 当前预估总步数，可动态调整
+
+### Optional Fields
+
+- `isRevision` (boolean): 标记当前 thought 是否在修正先前思路
+- `revisesThought` (integer): 指明修正的是哪一个 thought
+- `branchFromThought` (integer): 指明从哪一个 thought 开始分支
+- `branchId` (string): 当前分支标识符
+
+## Workflow Pattern
+
+```
+1. 从 `thoughtNumber: 1` 开始。
+2. 每一步：
+   - 在 `thought` 中表达当前推理
+   - 用 `totalThoughts` 估计整体范围，必要时调整
+   - 若还需继续，设置 `nextThoughtNeeded: true`
+3. 当结论已经足够清晰时，设置 `nextThoughtNeeded: false`
+```
+
+## Example 1: 基础推演 (Baseline Reasoning)
+
+```typescript
+// First thought
+{
+  thought: "问题表面上是“查询性能下降”，但先不要急着选优化手段。需要先把问题拆成三层：是单条 SQL 退化、接口级 N+1、还是更上层的调用放大。若根因没分清，后面的缓存、索引、重写都可能只是补丁。",
+  thoughtNumber: 1,
+  totalThoughts: 4,
+  nextThoughtNeeded: true
+}
+
+// Second thought
+{
+  thought: "从查询日志看，用户详情接口在一次请求里触发了大量重复读取，已经出现明显的 N+1 信号。但还不能直接下结论，因为重复查询也可能只是症状；需要继续确认慢点究竟来自“查询次数过多”，还是“某条关键查询本身很慢”。因此总步数上调一档。",
+  thoughtNumber: 2,
+  totalThoughts: 6,
+  nextThoughtNeeded: true
+}
+
+// Final thought
+{
+  thought: "结论可以收敛了：主因是列表页批量加载时触发的 N+1，次因是关联字段缺少索引放大了单次查询成本。优化顺序应该先消除 N+1，再补索引验证尾延迟；这样既先打掉主矛盾，也避免一上来引入缓存复杂度。",
+  thoughtNumber: 6,
+  totalThoughts: 6,
+  nextThoughtNeeded: false
+}
+```
+
+## Example 2: 修正前提 (Revision in Flight)
+
+```typescript
+{
+  thought: "回看 profiling 结果后，前面的判断需要修正：真正拖垮接口的不是 N+1 本身，而是关联列缺少索引，导致每次关联查询都在放大全表扫描成本。也就是说，N+1 仍然存在，但它不是第一性瓶颈，优先级应该后移。",
+  thoughtNumber: 4,
+  totalThoughts: 6,
+  isRevision: true,
+  revisesThought: 2,
+  nextThoughtNeeded: true
+}
+```
+
+## Example 3: 复杂变更拆解 (Structured Impact Analysis)
+
+```typescript
+{
+  thought: "用户一次性提出了多项规则修改，不该把它们当成同一种改动处理。先拆开看：有的是机制原则调整，有的是数值平衡，有的是接口语义变化，还有的是文档与实现脱节。如果不先分型，后面会把“该改 ADR 的”“该改设计文档的”“该补代码契约的”混成一锅。",
+  thoughtNumber: 1,
+  totalThoughts: 3,
+  nextThoughtNeeded: true
+}
+
+{
+  thought: "先做影响矩阵。机制原则类改动通常会回流到 ADR 和 System Design；数值平衡会影响规则表、配置与测试基线；接口语义变化最危险，因为它会悄悄破坏调用方的假设。这里最该警惕的不是改动数量，而是有没有改到“被多个模块默认依赖、但文档里没写清楚”的隐性契约。",
+  thoughtNumber: 2,
+  totalThoughts: 3,
+  nextThoughtNeeded: true
+}
+
+{
+  thought: "可以收敛了：先处理那些会改变系统边界或调用语义的项，再处理数值与体验层面的项。顺序上应优先修正文档与契约，再讨论平衡性；否则后续所有实现和评审都会建立在漂移的前提上。结论不是“先改最显眼的”，而是“先修最容易污染系统认知的”。",
+  thoughtNumber: 3,
+  totalThoughts: 3,
+  nextThoughtNeeded: false
+}
+```
+
+## Example 4: 分支比较 (Branching Trade-offs)
+
+```typescript
+// Branch A
+{
+  thought: "方案 A：先引入缓存削峰。好处是见效快、对接口层侵入小，适合先止血；坏处是会把问题从“数据库慢”转成“缓存一致性与失效策略复杂”，如果根因其实是查询设计不合理，这条路容易把偶然复杂度永久留在系统里。",
+  thoughtNumber: 3,
+  totalThoughts: 7,
+  branchFromThought: 2,
+  branchId: "cache",
+  nextThoughtNeeded: true
+}
+
+// Branch B
+{
+  thought: "方案 B：直接做索引优化和查询重写。好处是从根上消除瓶颈，长期结构更干净；代价是需要更仔细验证写入放大、锁竞争和回归风险。这条路更慢，但如果业务模型稳定，通常比提前上缓存更符合简单优先的原则。",
+  thoughtNumber: 3,
+  totalThoughts: 7,
+  branchFromThought: 2,
+  branchId: "query",
+  nextThoughtNeeded: true
+}
+```
+
+## Heuristic Reminders
+
+以下提醒是**辅助思考的启发式问题**，不是硬约束。按任务性质选择性使用即可。
+
+- **问题定义提醒**: 你现在是在描述现象，还是在定位根因？
+- **证据提醒**: 当前判断基于事实、观察结果，还是基于猜测与假设？
+- **边界提醒**: 当前问题影响的是局部模块、单系统，还是跨系统结构？
+- **复杂度提醒**: 你是在消除本质复杂度，还是在增加偶然复杂度？
+- **收敛提醒**: 当前是否已经足够形成结论，还是仍在无效发散？
+
+## Tips
+
+- 先给出粗略的 `totalThoughts`，随着理解深入再调整
+- 当早期假设被证伪时，优先修正，不要沿着错误前提继续推进
+- 当存在明确替代路径时，可以用分支并行比较
+- 在 `thought` 中明确表达不确定性，比过早下结论更可靠
+- 最后一个 thought 应明确给出结论，必要时补充下一步行动
+

package/templates/.agents/skills/spec-writer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: spec-writer
+description: 将模糊或高层需求转化为严格的产品需求文档（PRD）。适用于需求含糊、范围过大或表达停留在概念层的场景。
+---
+
+# 需求侦探手册
+
+> “软件开发最难的部分，不是如何实现，而是精确定义到底要实现什么。”
+
+你的任务是**消灭歧义**。
+
+## ⚡ 快速开始
+
+1.  **阅读需求（强制）**：阅读用户请求与上下文，识别其中的“感觉词”（如“快”“现代”“简单”）。
+2.  **深度思考（关键）**：你**必须**进行 3-7 轮结构化推理（视复杂度而定），完成以下工作：
+    *   提取 User Story（As a X, I want Y, so that Z）
+    *   识别歧义点
+    *   起草澄清问题
+3.  **追问澄清**：向用户提出问题。**未获得答案前不得继续**。
+4.  **起草 PRD（强制）**：读取 `references/prd_template.md`，然后创建 `.anws/v{N}/01_PRD.md`。
+5.  **歧义扫描（强制）**：起草完成后，执行下文的“10 维歧义扫描”。对发现的问题就地修正，或标记为 `[ASSUMPTION]`。
+6.  **User Story 质量闸门（强制）**：验证每条 User Story 都通过下文质量检查表。
+
+## 🛑 强制步骤
+在创建 PRD 之前，你**必须**：
+1. 提取至少 3 条清晰的 User Story。
+2. 定义至少 3 条 Non-Goal（明确**不做什么**）。
+3. 向用户澄清“感觉词”（例如：“快”具体意味着什么？“现代”指什么？）。
+4. 创建输出文件，**不要只在聊天里打印内容**。
+
+在创建 PRD 之后，你**必须**：
+5. 执行“10 维歧义扫描”，修复或标记所有 `Partial` / `Missing` 项。
+6. 验证每条 User Story 都具备：优先级 / 独立可测 / 涉及系统 / 边界情况。
+7. 确保 `[NEEDS CLARIFICATION]` 标签数量 ≤ 3（硬限制）。若超出，则采用合理默认值并加 `[ASSUMPTION]` 标签。
+
+## ✅ 完成检查清单
+- [ ] PRD 文件已创建：`.anws/v{N}/01_PRD.md`
+- [ ] 包含 User Stories、验收标准、Non-Goals
+- [ ] 每条需求都可测试、可度量
+- [ ] 用户已确认 PRD
+
+## 🛠️ 方法工具
+
+### 1. 苏格拉底追问
+*   **用户**：“我希望它很快。”
+*   **你**：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
+*   *目标*：把形容词转成数字和可验证标准。
+
+### 2. 上下文压缩
+*   **输入**：500 行聊天记录。
+*   **动作**：提取 *User Stories*，即 “As a User, I want X, so that Y.”
+*   **丢弃**：过早出现的实现细节（例如“使用 Redis”）。
+
+### 3. Non-Goal 设定（画圈）
+*   明确定义我们**不做什么**。
+*   *为什么*：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。
+
+## ⚠️ 侦探守则
+
+1.  **契约优先**：如果无法验证，就不要写进 PRD。
+2.  **不抢设计工作**：描述 *做什么*，不要过早写 *怎么做*。实现方式留给架构设计阶段。
+3.  **用户价值优先**：每条需求都必须能追溯到明确的用户价值。
+
+## 🧰 工具箱
+*   `references/prd_template.md`：产品需求文档模板。
+
+## 🔍 10 维歧义扫描
+
+起草 PRD 后，你**必须**从以下 10 个维度系统性扫描全文。这一步是为了用**可重复、可穷尽**的方法替代随意的“还有问题吗？”。
+
+对每个维度，标记状态：`Clear` ✅ / `Partial` ⚠️ / `Missing` ❌
+
+| # | 维度 | 检查内容 | 状态 |
+|---|------|----------|:------:|
+| 1 | **功能范围与行为** | 核心目标 / 成功标准 / 明确排除项 / 用户角色区分 | |
+| 2 | **领域与数据模型** | 实体、属性、关系 / 唯一性规则 / 生命周期与状态转换 / 数据规模假设 | |
+| 3 | **交互与 UX 流程** | 关键用户路径 / 错误、空状态、加载状态 / 无障碍与 i18n | |
+| 4 | **非功能质量** | 性能 / 可扩展性 / 可靠性 / 可观测性 / 安全与隐私 / 合规 | |
+| 5 | **集成与外部依赖** | 外部服务失败模式 / 导入导出格式 / 协议版本假设 | |
+| 6 | **边界情况与失败场景** | 负向场景 / 限流 / 并发冲突处理 | |
+| 7 | **约束与权衡** | 技术约束 / 显式权衡记录 / 被否决的备选架构 | |
+| 8 | **术语一致性** | 标准术语表 / 同义词在全文中的统一 | |
+| 9 | **完成信号** | 验收标准是否可测 / DoD 是否可量化 | |
+| 10 | **占位符与模糊词** | TODO 标记 / 未量化形容词（快、可扩展、安全、直观、健壮） | |
+
+**规则**：
+- 对于 `Partial` 或 `Missing` 项，按 **影响 × 不确定性** 排序，选取前 **5 个**向用户追问
+- **一次只问一个问题**；给出推荐答案；用户可接受或自定义
+- 用户回答后，**原子化写入**对应 PRD 段落，不允许保留互相矛盾的文本
+- `[NEEDS CLARIFICATION]` 标签数量**硬限制 ≤ 3**；若仍超出，则采用合理默认值并加 `[ASSUMPTION: ...]`
+- **不要向用户追问这些合理默认值**：行业通用的数据保留策略、标准 Web/移动性能预期、带兜底的友好错误提示、标准 Session 或 OAuth2 认证
+
+## ✅ User Story 质量闸门
+
+PRD 中的每条 User Story，在 PRD 被视为完成前，**都必须**通过以下检查：
+
+| 检查项 | 要求 |
+|-------|------|
+| **唯一 ID** | 必须带 `[REQ-XXX]` 以便追踪 |
+| **优先级** | 标记为 P0 / P1 / P2，且 P0 必须排前 |
+| **独立可测** | 说明该故事如何**独立**演示和验证 |
+| **涉及系统** | 列出具体系统 ID（必须与 `02_ARCHITECTURE_OVERVIEW.md` 对齐） |
+| **验收标准** | 至少 1 条 Given-When-Then + 至少 1 个错误场景 |
+| **边界情况** | 至少识别 1 个边界条件 |
+| **无模糊感觉词** | 不允许出现未量化形容词（如快 → <100ms p99，可扩展 → 支持 N 用户） |
+| **用户价值** | 用一句话描述对终端用户的价值 |
+
+若任一 User Story 未通过检查，**必须先修复，再交付 PRD**。

package/templates/{.agent → .agents}/skills/spec-writer/references/prd_template.md

@@ -109,7 +109,7 @@ flowchart TD
 ---
 
 ## 6. 约束与限制 (Constraint Analysis)
-<!-- 约束决定了技术选型的天花板。来自于 /scout 报告或立项时的不可抗力。 -->
+<!-- 约束决定了技术选型的天花板。来自于 /probe 报告或立项时的不可抗力。 -->
 
 ### 6.1 技术约束 (Technical Constraints)
 *   **遗留系统**: [例如: 必须兼容老版本的 MySQL 5.7 表结构]

package/templates/{.agent → .agents}/skills/system-architect/SKILL.md

@@ -16,7 +16,7 @@ description: 识别项目中的独立系统，定义系统边界。产出系统
  ## ⚠️ 强制深度思考
  
  > [!IMPORTANT]
- > 在进行拆解之前，你**必须**调用 `sequential thinking` 工具，视复杂情况进行 **3—7 步**推理。
+ > 在进行拆解之前，你**必须**使用 `sequential-thinking` skill，视复杂情况组织 **3—7 个 thought** 推理。
  > 思考内容例如：
  > 1.  "这个系统是否可以合并到另一个系统？"
  > 2.  "拆分是否真正带来价值（独立部署、技术栈差异）？"
@@ -171,7 +171,7 @@ description: 识别项目中的独立系统，定义系统边界。产出系统
 
 ## 📋 输出格式：Architecture Overview 模板
 
-使用以下结构产出 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`：
+使用以下结构产出 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`：
 
 ```markdown
 # 系统架构总览 (Architecture Overview)
@@ -610,7 +610,7 @@ Frontend → Backend → Database
 ```
 
 **Step 5: 产出Architecture Overview**
-使用模板填充内容 → 保存到 `genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md`
+使用模板填充内容 → 保存到 `.anws/v{N}/02_ARCHITECTURE_OVERVIEW.md`
 
 ---
 

package/templates/.agents/skills/system-architect/references/rfc_template.md

@@ -0,0 +1,59 @@
+# 技术设计说明（RFC / 技术规格）
+
+**PRD 参考**: [链接到 PRD]
+**功能名称**: [功能名称]
+**状态**: 草稿
+
+## 1. 高层设计
+### 架构图（Mermaid）
+<!-- 使用 Mermaid 展示数据流 -->
+```mermaid
+graph TD
+    A[用户] -->|操作| B[组件]
+    B -->|API 调用| C{服务}
+```
+
+### 组件层级
+*   `父组件`
+    *   `子组件A`（Props: x, y）
+    *   `子组件B`（State: z）
+
+## 2. API 契约（接口签名）
+<!-- 关键：定义精确签名。禁止幻觉。 -->
+
+### 接口端点
+*   `POST /api/v1/resource`
+    *   **请求体**：
+        ```typescript
+        interface CreateRequest {
+          field: string; // 必填
+        }
+        ```
+    *   **响应**：`200 OK`（Schema 见下）
+
+### 函数接口
+<!-- 关键内部函数签名 -->
+```typescript
+function calculateSomething(input: InputType): ResultType
+```
+
+## 3. 数据模型策略
+### 数据库 Schema 变更
+```sql
+-- 在这里填写 DDL
+CREATE TABLE ...
+```
+
+### 状态管理
+*   全局状态：[例如 Redux / Zustand slice]
+*   本地状态：[例如 React.useState]
+
+## 4. 实施步骤
+<!-- 原子化、按顺序的实施步骤 -->
+1.  [步骤 1：数据库迁移]
+2.  [步骤 2：后端 API]
+3.  [步骤 3：前端界面]
+
+## 5. 安全与风险
+*   **认证**：[如何保证访问安全？]
+*   **校验**：[使用什么输入校验方案？]

package/templates/{.agent → .agents}/skills/system-designer/SKILL.md

@@ -31,7 +31,7 @@ description: 为单个系统设计详细的技术文档。负责架构图、接
 
 ✅ **正确做法**：
 - **调研驱动** - 先用 /explore 调研最佳实践
-- **深度思考** - 用 sequential thinking 3-7 步设计
+- **深度思考** - 用 `sequential-thinking` skill 组织 3-7 个 thought 设计
 - **Trade-offs讨论** - Google Design Docs风格，说明权衡
 - **可视化架构** - 使用Mermaid绘制架构图和数据流图
 - **追溯链** - 引用PRD需求 [REQ-XXX]
@@ -59,7 +59,7 @@ description: 为单个系统设计详细的技术文档。负责架构图、接
 
 ### 3. **Decompose (分解)**
 - **输入**: 调研报告 + 系统理解
-- **行动**: 使用 sequential thinking 分解系统
+- **行动**: 使用 `sequential-thinking` skill 分解系统
 - **问题**:
   - "核心组件有哪些？各自职责？"
   - "组件之间如何通信？"
@@ -180,7 +180,7 @@ description: 为单个系统设计详细的技术文档。负责架构图、接
 ---
 
 ### 守则2: 深度思考，不拍脑袋
-**规则**: 使用 `sequential thinking` **3—7 步**设计，视复杂情况而定。
+**规则**: 使用 `sequential-thinking` skill 组织 **3—7 个 thought**设计，视复杂情况而定。
 
 **为什么？** 设计是复杂活动，需要系统性思考。
 
@@ -364,7 +364,7 @@ flowchart TD
 - **使用**: `view_file .agent/skills/system-designer/references/system-design-detail-template.md`
 
 ### 工具3: 调研报告存储
-- **路径**: `genesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
+- **路径**: `.anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
 - **用途**: 保存 /explore 的调研结果
 - **格式**: Exploration Report (由 /explore 生成)
 
@@ -507,7 +507,7 @@ flowchart TD
 
 **Step 3-5: 分解 + 设计 + 防御**
 ```
-使用 sequential thinking 3—7 步:
+使用 `sequential-thinking` 组织 3—7 个 thought:
 1. 采用分层架构 (Presentation → Business → Data)
 2. 核心组件: AuthService, UserService, DatabaseManager
 3. API设计: POST /auth/login, GET /users/me
@@ -522,7 +522,7 @@ flowchart TD
 **Step 6: 文档化 (Document)**
 ```
 使用模板填充14章节 → 保存到:
-genesis/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
+.anws/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
 ```
 
 ---

package/templates/{.agent → .agents}/skills/system-designer/references/system-design-template.md

@@ -268,45 +268,95 @@ classDiagram
 ## 8. Trade-offs & Alternatives (权衡与备选方案)
 <!-- ⚠️ CRITICAL: Google Design Docs风格 - 说明为什么选A而不是B -->
 
-### 8.1 Decision 1: 为什么用PostgreSQL而不是MongoDB？
+> [!IMPORTANT]
+> **ADR 引用规则 (单向引用链)**
+>
+> **为什么**: 决策只记录一次,其他地方只引用不复制。这样修改 ADR 时,所有 SYSTEM_DESIGN 通过引用自动关联,不会遗漏。
+>
+> **规则**:
+> - 如果决策已在 ADR 中记录,**只引用不复制**
+> - 引用格式: `> **决策来源**: [ADR-XXX: 决策标题](../03_ADR/ADR_XXX.md)`
+> - 本系统特有的决策才在此详细说明
+>
+> **自检示例**:
+>
+> ❌ **错误** - 复制 ADR 内容:
+> ```markdown
+> ### 8.1 数据库选型
+> 我们选择 PostgreSQL 因为:
+> - ACID 保证
+> - JSON 支持
+> - 团队熟悉
+> (这些理由已在 ADR-001 中记录,不应复制)
+> ```
+>
+> ✅ **正确** - 引用 ADR:
+> ```markdown
+> ### 8.1 数据库选型
+> > **决策来源**: [ADR-001: 技术栈选型](../03_ADR/ADR_001_TECH_STACK.md)
+> >
+> > 本系统使用 ADR-001 定义的 PostgreSQL。
+> >
+> > **本系统特有配置**: 连接池大小 20,使用 asyncpg 异步驱动
+> ```
+
+### 8.1 [跨系统决策] - 引用 ADR
+
+<!-- 如果此决策影响多个系统，应在 ADR 中记录 -->
+
+> **决策来源**: [ADR-XXX: 决策标题](../03_ADR/ADR_XXX.md)
+>
+> 本系统实现 ADR-XXX 定义的设计，不在此重复决策理由。
+>
+> **本系统特有实现**: [补充本系统如何实现该决策]
+
+---
+
+### 8.2 [本系统特有决策] - 详细说明
+
+<!-- 如果此决策只影响本系统，在此详细说明 -->
 
-**Option A: PostgreSQL (✅ Selected)**
+**Option A: [名称] (✅ Selected)**
 - ✅ **优点**: 
-  - ACID保证，强一致性
-  - 关系型数据适合我们的用户-权限模型
-  - 团队熟悉SQL，学习成本低
-  - JSON支持满足灵活性需求
+  - ...
 - ❌ **缺点**:
-  - 横向扩展不如NoSQL简单
-  - Schema变更需要migration
+  - ...
 
-**Option B: MongoDB**
+**Option B: [名称]**
 - ✅ **优点**:
-  - 灵活Schema，易于快速迭代
-  - 天然横向扩展
+  - ...
 - ❌ **缺点**:
-  - 我们需要强一致性（用户认证）
-  - 关系查询复杂
-  - 团队不熟悉
+  - ...
 
-**Decision**: 选择PostgreSQL，因为**数据一致性**比灵活性更重要。未来如果需要扩展，可以考虑读写分离+分片。
+**Decision**: 选择 [Option A]，因为 [核心理由]。
 
 ---
 
-### 8.2 Decision 2: 认证方式选择
+<!-- 示例：引用 ADR 的决策 -->
+### 8.x 示例: 数据库选型 (引用 ADR)
 
-**Option A: JWT (✅ Selected)**
-- ✅ 无状态，易于横向扩展
-- ✅ 前后端分离友好
-- ❌ Token无法主动撤销
+> **决策来源**: [ADR-001: 技术栈选型](../03_ADR/ADR_001_TECH_STACK.md)
+>
+> 本系统使用 ADR-001 定义的 PostgreSQL 作为主数据库。
+>
+> **本系统特有配置**:
+> - 连接池大小: 20
+> - 使用 asyncpg 异步驱动
 
-**Option B: Session**
-- ✅ 可撤销
-- ❌ 需要共享Session存储（如Redis）
+---
 
-**Decision**: 选择JWT + 黑名单机制（Redis存储被撤销的token ID），兼顾两者优点。
+<!-- 示例：本系统特有决策 -->
+### 8.y 示例: 缓存策略 (本系统决策)
 
----
+**Option A: Redis (✅ Selected)**
+- ✅ 高性能，团队熟悉
+- ❌ 需要额外运维
+
+**Option B: 内存缓存**
+- ✅ 简单
+- ❌ 不支持分布式
+
+**Decision**: 选择 Redis，因为本系统需要支持多实例部署。
 
 ## 9. 安全性考虑 (Security Considerations)
 

package/templates/{.agent → .agents}/skills/task-planner/SKILL.md

@@ -301,7 +301,7 @@ graph TD
 
 ## 🧰 工具箱
 
-> **输出路径**: 任务清单应保存到 `genesis/v{N}/05_TASKS.md`，由调用方 (blueprint workflow) 指定具体的 `v{N}` 版本号。
+> **输出路径**: 任务清单应保存到 `.anws/v{N}/05_TASKS.md`，由调用方 (blueprint workflow) 指定具体的 `v{N}` 版本号。
 
 ### 工具1: Tasks模板
 使用WBS三级层次结构组织任务。