@namewta/speculo 0.1.0

package/speculo/workflows/dev/03-tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# 深模块
+
+来自《A Philosophy of Software Design》：
+
+**深模块** = 小接口 + 大量实现
+
+```
+┌─────────────────────┐
+│     小接口           │  ← 方法少，参数简单
+├─────────────────────┤
+│                     │
+│                     │
+│     深层实现         │  ← 复杂逻辑被隐藏
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**浅模块** = 大接口 + 很少实现（应避免）
+
+```
+┌─────────────────────────────────┐
+│           大接口               │  ← 方法多，参数复杂
+├─────────────────────────────────┤
+│  薄实现                         │  ← 只是透传
+└─────────────────────────────────┘
+```
+
+设计接口时，问自己：
+
+- 能否减少方法数量？
+- 能否简化参数？
+- 能否把更多复杂性隐藏在里面？

package/speculo/workflows/dev/03-tdd/interface-design.md

@@ -0,0 +1,31 @@
+# 面向可测试性的接口设计
+
+好的接口让测试变得自然：
+
+1. **接受依赖，而不是自己创建**
+
+   ```typescript
+   // 易于测试
+   function processOrder(order, paymentGateway) {}
+
+   // 难以测试
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **返回结果，而不是产生副作用**
+
+   ```typescript
+   // 易于测试
+   function calculateDiscount(cart): Discount {}
+
+   // 难以测试
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **小表面积**
+   - 方法越少 = 需要的测试越少
+   - 参数越少 = 测试准备越简单

package/speculo/workflows/dev/03-tdd/mocking.md

@@ -0,0 +1,60 @@
+# 何时使用 Mock
+
+只在**系统边界**处 mock：
+
+- 外部 API（支付、邮件等）
+- 数据库（有时——优先考虑测试数据库）
+- 时间/随机性
+- 文件系统（有时）
+
+不要 mock：
+
+- 你自己的类/模块
+- 内部协作者
+- 任何你能控制的东西
+
+## 为可 Mock 性设计
+
+在系统边界处，设计易于 mock 的接口：
+
+**1. 使用依赖注入**
+
+将外部依赖传入，而不是在内部创建：
+
+```typescript
+// 易于 mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// 难以 mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. 优先使用 SDK 风格的接口，而非通用 fetcher**
+
+为每个外部操作创建专用函数，而不是一个带条件逻辑的通用函数：
+
+```typescript
+// 好：每个函数都可以独立 mock
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// 坏：mock 时需要在内部写条件逻辑
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+SDK 方式意味着：
+
+- 每个 mock 返回一种特定的数据结构
+- 测试准备中不需要条件逻辑
+- 更容易看出测试覆盖了哪些端点
+- 每个端点都有类型安全

package/speculo/workflows/dev/03-tdd/refactoring.md

@@ -0,0 +1,10 @@
+# 重构候选
+
+TDD 循环后，寻找以下问题：
+
+- **重复** → 提取函数/类
+- **长方法** → 拆分为私有辅助方法（保持测试只测公共接口）
+- **浅模块** → 合并或加深
+- **特性嫉妒（Feature Envy）** → 把逻辑移到数据所在的地方
+- **基本类型偏执** → 引入值对象
+- **现有代码**被新代码揭示出问题

package/speculo/workflows/dev/03-tdd/tdd-finish.md

@@ -0,0 +1,28 @@
+# Finish Phase
+
+## 输入
+
+- `implementation-log.md`
+- 项目验证命令和变更 diff
+- `03-tdd.md` 中的内置 TDD 指引和同目录 `refactoring.md`
+
+## 产物
+
+- `.speculo/dev/<change>/verification.md`，由 `../_templates/tdd-verification-template.md` 填写
+
+## 填写引导
+
+1. 运行与变更相关的测试、类型检查、lint 或构建命令。
+2. 记录无法运行的命令和阻塞原因。
+3. 搜索临时调试标记、一次性脚本和推测性实现。
+4. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
+
+## 边界
+
+- 不自动归档 change；归档由 `commands/archive.md` 负责。
+- 不修改 `.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
+
+## 完成准则
+
+- `verification.md` 无残留 `[TODO:]`
+- `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

package/speculo/workflows/dev/03-tdd/tdd-loop.md

@@ -0,0 +1,33 @@
+# Slice Loop Phase
+
+## 输入
+
+- `tdd-plan.md`
+- `slices.md` 或用户确认的切片顺序
+- `03-tdd.md` 中的内置 TDD 指引和同目录辅助文档
+
+## 产物
+
+- `.speculo/dev/<change>/implementation-log.md`，由 `../_templates/tdd-log-template.md` 填写
+- 可选：`tasks/00-INDEX.md` 与 `tasks/TNN.md`，由 workflow 自治创建
+
+## 填写引导
+
+1. 每次只选择一个切片和一个行为。
+2. RED：写一个通过公共接口验证行为的失败测试。
+3. GREEN：写最少实现使当前测试通过。
+4. REFACTOR：只在绿色状态下整理设计。
+5. 每轮记录测试名、失败信号、实现摘要、重构摘要和验证命令。
+6. 每轮检查：测试描述行为而非实现；测试只使用公共接口；测试能经受内部重构；代码是当前测试的最少实现；没有添加推测性功能。
+
+## 边界
+
+- 不预实现未来切片。
+- 不使用内部实现细节作为主要断言。
+- 不在 RED 状态下重构。
+
+## 完成准则
+
+- 每个完成切片都有 RED/GREEN/REFACTOR 记录
+- `implementation-log.md` 无残留 `[TODO:]`
+- `.status.json` 已追加 `red_green_refactor_cycles`

package/speculo/workflows/dev/03-tdd/tdd-plan.md

@@ -0,0 +1,30 @@
+# TDD Plan Phase
+
+## 输入
+
+- `prd.md`、`slices.md`、`diagnosis.md` 或用户明确任务
+- 项目测试命令、现有测试样式和公共接口
+- `03-tdd.md` 中的内置 TDD 指引和同目录辅助文档
+
+## 产物
+
+- `.speculo/dev/<change>/tdd-plan.md`，由 `../_templates/tdd-plan-template.md` 填写
+
+## 填写引导
+
+1. 遵循 `03-tdd.md` 的内置 TDD 指引。
+2. 按需读取同目录的接口设计、测试、mock 和 deep module 文档。
+3. 与用户确认公共接口、最重要的行为和测试覆盖优先级。
+4. 拆出第一个 tracing slice，避免水平切片。
+5. 探索代码库时使用项目领域术语表，确保测试名称和接口词汇与项目语言一致，并尊重触及区域的 ADR。
+6. 写任何代码前确认接口变更、优先测试的行为、deep module 机会、可测试接口设计和行为列表。
+
+## 边界
+
+- 本阶段不写代码。
+- 不批量预写所有测试。
+
+## 完成准则
+
+- `tdd-plan.md` 无残留 `[TODO:]`
+- `.status.json` 的 `implementation_status` 为 `planned`

package/speculo/workflows/dev/03-tdd/tests.md

@@ -0,0 +1,61 @@
+# 好测试与坏测试
+
+## 好测试
+
+**集成式**：通过真实接口测试，而不是 mock 内部组件。
+
+```typescript
+// 好：测试可观察的行为
+test("用户可以用有效购物车结算", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+特征：
+
+- 测试用户/调用者关心的行为
+- 只使用公共 API
+- 能经受住内部重构
+- 描述「做什么」，而不是「怎么做」
+- 每个测试一个逻辑断言
+
+## 坏测试
+
+**实现细节测试**：与内部结构耦合。
+
+```typescript
+// 坏：测试实现细节
+test("checkout 调用了 paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+危险信号：
+
+- mock 内部协作者
+- 测试私有方法
+- 断言调用次数/顺序
+- 重构时测试坏了但行为没变
+- 测试名称描述的是「怎么做」而不是「做什么」
+- 通过外部手段验证而不是通过接口
+
+```typescript
+// 坏：绕过接口来验证
+test("createUser 保存到数据库", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// 好：通过接口验证
+test("createUser 使用户可被检索", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/speculo/workflows/dev/D-docs-sync/D-docs-sync.md

@@ -0,0 +1,97 @@
+---
+id: dev/D-docs-sync
+category: dev
+name: Docs Sync
+description: 基于 git 差异增量同步 README、CHANGELOG、AGENTS 等对外文档
+keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
+---
+
+# Docs Sync 工作流执行指引
+
+本工作流是 `dev/D` 入口，用于把一段 git 差异映射回对外文档。它只做差量同步，不从零创建文档，也不做整页重写。
+
+## 内置指引
+
+### Iron Law
+
+禁止在不读取 `.speculo/dev/docs-sync-state.json` 的 `last_sync_sha` 与当前 `HEAD` 之间 diff 的情况下修改任何对外文档。
+
+如果 diff 为空，或只有文档自身变动，直接报告无需同步或空同步，并按规则推进 state；不要触碰无关文档。
+
+### 输入
+
+- `.speculo/dev/docs-sync-state.json`
+- 当前 git `HEAD`
+- state 中的 `tracked_docs` 列表
+- 当前 change 目录：`.speculo/dev/<change>/`
+
+### 输出
+
+- `.speculo/dev/<change>/docs-sync-report.md`
+- 更新后的 tracked docs
+- 更新后的 `.speculo/dev/docs-sync-state.json`
+
+### 渐进披露
+
+- `readme-contract.md`：更新 README 类文档时读取。
+- `agents-contract.md`：更新 AGENTS / AI 代理手册类文档时读取。
+- `changelog-contract.md`：更新 CHANGELOG 类文档时读取。
+- `state-json-schema.md`：初始化、读取或写回 docs-sync state 时读取。
+
+## 阶段
+
+### 1. State Read — 读取同步状态
+- 规范：`docs-sync-state.md`
+- 模板：`../_templates/docs-sync-state-template.json`
+- 产物：`.speculo/dev/docs-sync-state.json`
+- 完成准则：
+  - 已确定 `LAST_SYNC_SHA` 和 `HEAD_SHA`
+  - 首次运行时已初始化 state 并要求用户确认 `tracked_docs`
+
+### 2. Diff Collect — 收集 git 差异
+- 规范：`docs-sync-diff.md`
+- 模板：无
+- 产物：`docs-sync-report.md`
+- 完成准则：
+  - 已记录 git log、name-status、shortstat 和路径分组
+  - 已判断是否需要修改文档
+
+### 3. Docs Update — 差量更新文档
+- 规范：`docs-sync-update.md`
+- 模板：`../_templates/docs-sync-report-template.md`
+- 产物：`docs-sync-report.md`
+- 完成准则：
+  - 只修改 `tracked_docs` 中需要同步的文档
+  - README / CHANGELOG / AGENTS 类文档遵守对应 contract
+  - `docs-sync-report.md` 无残留 `[TODO:]`
+
+### 4. State Write — 验证与写回状态
+- 规范：`docs-sync-finish.md`
+- 模板：`../_templates/docs-sync-report-template.md`
+- 产物：`.speculo/dev/docs-sync-state.json`
+- 完成准则：
+  - 已运行项目级校验或记录无法运行原因
+  - state 已原子写入
+  - 已向用户报告范围、改动文档和新基线
+
+## 依赖
+
+- 软依赖：无
+- 硬依赖：git 仓库；首次运行需要用户确认 `tracked_docs`
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/D`
+- `docs_sync_state_path` (string) — 固定为 `.speculo/dev/docs-sync-state.json`
+- `docs_sync_range` (string) — `<LAST_SYNC_SHA>..HEAD`
+- `tracked_docs` (array) — 本次纳入同步的文档
+- `synced_docs` (array) — 本次实际修改的文档
+- `docs_sync_status` (first-run | no-op | updating | synced | blocked) — 同步状态
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- 只有验证完成后才原子写回 `.speculo/dev/docs-sync-state.json`。
+- 本 workflow 不自动完成 change；用户要求仅同步文档时，可在报告完成后把 `change_status` 置为 `completed`。

package/speculo/workflows/dev/D-docs-sync/agents-contract.md

@@ -0,0 +1,95 @@
+# AI 代理手册类文档同步契约（通用）
+
+AI 代理手册类文档（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.github/copilot-instructions.md` 等）是**给 AI 代理看的工作手册**，不是给用户看的营销页。它的受众是其他 AI 代理（Claude / Cursor / Kiro / Codex / GPT / Gemini 等），内容应是高信息密度的结构化陈述。
+
+本契约给出通用写作与同步规则；具体章节结构由项目自身现有文档决定，同步时保留既有结构做差量更新。
+
+## 文档定位
+
+- 不是用户文档，不需要 Quick Start 式教程
+- 不是营销文，不需要"它多强大"
+- 是**事实手册**：项目身份、目录布局、关键命令、扩展机制、禁止与必须
+- 是**惯例沉淀**：代码风格、测试要求、发布约定、常见陷阱
+
+## 典型章节
+
+以下是 AI 代理手册中**常见**的章节；实际是否存在、顺序如何，由项目决定：
+
+| 常见章节 | 通用同步触发条件 |
+|---------|-----------------|
+| 项目身份 | `package.json` / `pyproject.toml` / `Cargo.toml` 等元信息变化（name / version / runtime 约束 / license） |
+| 核心架构 | 顶层领域模型、核心抽象、关键常量集变化 |
+| 仓库布局 | 顶层目录树变化（新增/删除/重命名） |
+| 开发命令 | 项目任务运行器入口变化（scripts / Makefile / justfile） |
+| CLI / API 速查 | CLI 入口或公共 API 变化 |
+| 扩展机制 | 钩子、插件、生命周期钩子的 public API 变化 |
+| 代理行为规约 | 代码风格、测试要求、发布约定的策略性调整（变化频率低） |
+| 常见陷阱 | CI 失败复盘、重构遗留约定、新成员反复犯错 |
+| 相关文档 | 新增/删除对外文档时 |
+
+## 仓库布局小节的同步规则
+
+如存在"仓库布局 / Repository Layout / 目录结构"章节，它是代码树的 ASCII 快照。**每次同步**都要对照实际顶层目录：
+
+- 列顶层目录 + 关键子目录（建议最多两层）
+- 用 `├──` `└──` `│` 表示树形
+- 右侧注释简短，说明"这个目录是做什么的"
+- 新增 / 删除 / 重命名顶层目录时必须跟进
+
+## 开发命令与 CLI 速查
+
+- 表格形式（两列："场景 / 命令"，或三列："命令 / 作用 / 常用标志"）
+- 命令来自项目任务运行器（`package.json#scripts` / `Makefile` / etc.）或 CLI 入口源码
+- 新增命令 → 加一行；改名 → 改行；删除 → 删行
+- 与 README 的 CLI Reference **同源但更简略**：README 提供完整说明，代理手册只给速查
+
+## 扩展机制
+
+如项目提供钩子、插件、生命周期回调等二次开发入口，对应源文件的 public API 变化时必须同步此章节。代码示例应使用**实际存在的入口**，不要虚构。
+
+## 代理行为规约
+
+这是最稳定的章节。调整的触发条件有限：
+
+- 工具链升级（例如 ESLint flat config / legacy 切换、测试框架替换）
+- 构建 / 发布流水线改造
+- 代码风格或命名约定的全仓级调整
+
+## 常见陷阱
+
+每一条是一个真实踩过的坑或设计隐患。
+
+**添加条目的时机**：
+
+- CI 失败排查后发现某类错误反复出现
+- 重大重构后遗留的临时约定
+- 新团队成员或 AI 代理反复犯的同一错
+
+**删除条目的时机**：工具链或代码结构升级消除了该陷阱。
+
+## 相关文档
+
+指向项目的其他对外文档（README / CHANGELOG / CONTRIBUTING / spec 目录等）。新增顶层文档（如增加 `CONTRIBUTING.md`）时同步本小节。
+
+## 语言与风格
+
+- 全文使用**项目主要贡献者的工作语言**（中文项目用中文，英文项目用英文）
+- 代码实体（命令、路径、字段名、配置键、类名）保持**原文**，不翻译
+- 列表式陈述优先于长段落
+- 表格优先于散文
+- 代码块优先于描述
+- 使用硬约束语言：**禁止 / 必须 / 不得 / 强制**
+- 避免营销语、惊叹号、表情符号
+- 避免模糊词："通常 / 大概 / 可能"改为具体条件
+
+## 长度预算
+
+建议全文控制在 500 行以内（与渐进披露 L2 阈值一致）。超过时把具体细节下沉到 `references/` 子文档并在主文档中引用。
+
+## 不做的事
+
+- 不复述 README 里已讲过的"它解决什么问题"
+- 不写命令的详细 usage（`--help` 已经提供，速查表已经够）
+- 不加 Quick Start 类步骤教程（那是 README 的工作）
+- 不罗列借鉴项目清单（README 的致谢小节已经有了）
+- 不做版本变更历史（那是 CHANGELOG 的工作）

package/speculo/workflows/dev/D-docs-sync/changelog-contract.md

@@ -0,0 +1,155 @@
+# CHANGELOG 类文档同步契约（通用）
+
+CHANGELOG 类文档（`CHANGELOG.md`、`CHANGELOGS.md`、`HISTORY.md`、`RELEASES.md`）遵循 [Keep a Changelog 1.1.0](https://keepachangelog.com/1.1.0/) 格式与 [SemVer 2.0.0](https://semver.org/)。语言由项目决定（中/英/其他），日期建议采用 ISO 8601（UTC 或带时区偏移）。
+
+## 文档骨架（Keep a Changelog 约定）
+
+```
+# Changelog
+
+<简短介绍段：声明遵循 KaC + SemVer 等约定>
+
+---
+
+## [Unreleased]
+
+### Added / 新增
+### Changed / 变更
+### Deprecated / 弃用
+### Removed / 移除
+### Fixed / 修复
+### Security / 安全
+
+---
+
+## [x.y.z] — YYYY-MM-DD
+
+<同样的分节>
+
+---
+
+## 版本链接 / Links
+
+- [Unreleased](<compare-url>/vLATEST...HEAD)
+- [x.y.z](<releases-url>/tag/vx.y.z)
+- ...
+```
+
+`[Unreleased]` 顶部段落**永远存在**，即使内容为空。
+
+## 标准分节与可选扩展
+
+**Keep a Changelog 标准 6 节**（必须用标准名，语言本地化即可）：
+
+| 标准节 | 语义 |
+|------|------|
+| Added / 新增 | 新功能、新命令、新模板、新技能 |
+| Changed / 变更 | 既有能力的行为/默认值调整 |
+| Deprecated / 弃用 | 将来会移除但本版本仍能用 |
+| Removed / 移除 | 已从代码中删除的能力 |
+| Fixed / 修复 | bug 修复 |
+| Security / 安全 | 安全修复、CVE 响应、鉴权相关调整 |
+
+**常见非标准扩展**（项目可选）：
+
+| 扩展节 | 语义 |
+|-------|------|
+| Planned / 计划中 | 明确声明"即将做但未动工"的事项，用于路线图沟通 |
+| Docs / 文档 | 对外文档的更新（README / AGENTS / references 等） |
+| Performance / 性能 | 性能优化但行为未变 |
+| Dependencies / 依赖 | 依赖升级聚合（非 Security） |
+
+项目一旦采用某扩展节就在整个 CHANGELOG 内一致使用，不要忽隐忽现。**没有内容的分节不要列出空标题**；保留有内容的即可。
+
+## 把 git 变更写成 Changelog 条目
+
+[Conventional Commits](https://www.conventionalcommits.org/) 前缀对应分节（按项目采用的 commit 约定调整）：
+
+| 前缀 | 分节 |
+|------|------|
+| `feat:` / `feat(...):` | Added / 新增 |
+| `fix:` / `fix(...):` | Fixed / 修复 |
+| `refactor:` / `perf:` | Changed / 变更（若有行为影响）或 Performance |
+| `docs:` | Docs / 文档（如项目采用该扩展节）；否则不写 |
+| `chore:` / `ci:` / `build:` / `style:` / `test:` | 默认不写；仅在用户能感知时写入相应分节 |
+| `revert:` | 视被 revert 的内容归类 |
+| 依赖升级（Dependabot 等） | Security（有 CVE） / Dependencies 或 Changed（常规） |
+
+**不要把每一个 commit 都写成一行**。聚合为"主题条目"：
+
+- 同一主题下的多个 commit → 一条 bullet，列出关键细节
+- `chore:` 类型整批的 Dependabot 升级 → 一条"依赖周更"条目
+- 只影响开发体验（测试配置调整、lint 规则微调）通常不进 CHANGELOG
+
+示例（原始 commits → Changelog 条目）：
+
+```
+git log
+  feat(cli): add --json flag to status command
+  fix(status): handle missing config gracefully
+  test(status): cover --json output
+
+→ CHANGELOG 的 [Unreleased] 下：
+### Added
+- **CLI**：`status --json` 支持机器可读输出，缺失配置时给出空结构而非报错
+```
+
+## Tag 发版时的迁移
+
+当检测到区间内发生了版本 tag（即项目元信息中的 version 变化 + 新 `v*` tag）：
+
+1. 确定 tag 创建日期：`git log -1 --format=%aI vX.Y.Z`
+2. 把 `[Unreleased]` 下除"Planned / 计划中"外的所有条目整体移动到新版本段落 `## [X.Y.Z] — YYYY-MM-DD`
+3. 清空 `[Unreleased]`（保留空的"Planned / 计划中"区块，如项目使用该扩展节）
+4. 更新底部版本链接：
+   - 新增 `[X.Y.Z]` 链接行
+   - 把 `[Unreleased]` 的 compare 基线改为 `vX.Y.Z...HEAD`
+5. 如果 tag 之后还有新 commit，按正常流程把这些 commit 写入新的 `[Unreleased]`
+
+## 版本链接契约
+
+底部链接段落固定结构：
+
+```
+- [Unreleased](<repo>/compare/vLATEST...HEAD)
+- [X.Y.Z](<repo>/releases/tag/vX.Y.Z)
+- [X.Y.Z-1](...)
+- ...
+```
+
+每发一个新版本 → 加一行；`[Unreleased]` compare 基线始终指向最新 tag。仓库 URL 由项目决定（GitHub / GitLab / Gitea / Bitbucket）。
+
+## 条目写作规范
+
+- 每个 bullet 以**能力名或模块名**加粗开头，如 `**CLI**：...`、`**API**：...`、`**templates**：...`、`**build**：...`、`**CI**：...`
+- 用户视角描述"发生了什么"，不描述"怎么改的"
+- 路径、命令、标志、版本号保留代码格式（反引号）
+- 不使用表情符号
+- 一条 bullet 不超过两行；更长拆成子列表
+
+## 不做的事
+
+- **不要**重写已发布版本段落的条目措辞 —— 这些是历史档案
+- **不要**在 `[Unreleased]` 里保留已被移入正式版本的条目
+- **不要**反向覆盖：用 GitHub / GitLab 自动生成的 release notes 盖掉人工整理的 CHANGELOG
+- **不要**把文档自身同步写成 `Added / Changed` —— 如项目采用"Docs / 文档"扩展节归入该节；否则不写
+- **不要**把内部重构写成新功能
+
+## 示例：典型同步产物
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- **CLI**：`status --json` 输出机器可读状态
+- **templates**：新增 authentication 模板，覆盖常见登录模式
+
+### Changed
+
+- **doctor**：`--check-deps` 在检测到未知依赖时改为 warn（原 error）
+
+### Docs
+
+- 新增 `.agents/skills/docs-sync/`，用于基于 git diff 同步对外文档
+```