@betterdanlins/ai-memory 0.1.0 → 0.3.0

package/templates/claude/CLAUDE.md

@@ -4,14 +4,19 @@
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
 
-- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
-- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`;手动 /update-memory
-- 反驳检查 → /critic 或定稿流程内强制触发;必须派 critic subagent 独立上下文执行
+- 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
+- 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- M/L 级功能 how 与技术接口 → feature-design skill,产物在 `docs/design/vX.Y.Z/`;S 级可直接实现
+- 交付前 → delivery-readiness skill,按风险验证契约、测试、迁移、回滚、性能与可观测性
+- 记忆更新 → 只在可验收工程节点、关键决策、状态变化或会话切换时写;手动 /update-memory
+- 反驳检查 → S 级精简自检;M/L 级或用户明确要求时用 /critic 独立审查
 
 ## 与 superpowers 的编排(未安装则忽略本节)
 
-1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
-2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+1. final 需求已经确认 what/why,不要用 brainstorming 重复澄清目标与范围
+2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
+3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
+4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
 
 ## 项目信息
 

package/templates/codex/.agents/skills/critic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: critic
-description: Use when 需要对需求定稿、架构设计或实现方案做对抗性检查/反驳/挑毛病
+description: Use when an M/L-risk requirement, architecture baseline, or implementation design needs adversarial review, or when the user explicitly requests critique, rebuttal, or challenge
 ---
 
-读取 `.ai/skills/critic.md`,按四类清单攻击目标文档;输出带严重度的质疑列表后,逐条回应「接受并修改」或「有理由反驳」。刻意抵制为自己刚写内容辩护的倾向。
+读取 `.ai/skills/critic.md`,按四类清单攻击目标文档;输出带严重度的质疑列表后,逐条回应「接受并修改」或「有理由反驳」。S 级只做精简自检;M/L 级在当前工具无法提供独立上下文时降级自检,刻意抵制自我辩护。

package/templates/codex/.agents/skills/delivery-readiness/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: delivery-readiness
+description: Use when a feature is preparing to merge, release, deploy, or hand over and needs evidence-based verification of contracts, tests, migration, rollback, performance, observability, reliability, security, or operational readiness
+---
+
+读取并严格遵循 `.ai/skills/delivery-readiness.md`，按 S/M/L 风险检查适用项；不要重新执行需求澄清或技术设计。

package/templates/codex/.agents/skills/feature-design/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: feature-design
+description: Use when an M/L-risk finalized requirement needs implementation design, module or service boundaries, technical interface contracts, data-model changes, quality-attribute impact, migration, rollback, or an implementation-ready how document
+---
+
+读取并严格遵循 `.ai/skills/feature-design.md`，以 final 需求和项目架构基线为输入；不要重新讨论已确认的 what/why，也不要默认启动完整 Superpowers 流程。

package/templates/codex/.agents/skills/memory-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-update
-description: Use when 完成一个任务节点、做出关键决策、会话收尾,或用户要求更新记忆/总结进展
+description: Use when completing an independently verifiable feature, phase, or release; making a durable decision; changing requirement/design/delivery status; preserving a cross-session risk; switching tools; or when the user explicitly asks to update memory
 ---
 
 读取并严格遵循 `.ai/skills/memory-update.md` 的写入路由与硬性约束执行。

package/templates/codex/.agents/skills/project-inception/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: project-inception
+description: Use when starting a 0-to-1/greenfield project, establishing its first engineering and architecture baseline, or planning a major redesign that changes system boundaries, data ownership, deployment topology, or quality-attribute targets
+---
+
+读取并严格遵循 `.ai/skills/project-inception.md`，建立或增量更新 `docs/architecture/` 四份工程基线；普通功能迭代不要触发。

package/templates/codex/AGENTS.md

@@ -4,14 +4,19 @@
 
 进场先读 `.ai/memory/MEMORY.md`,随后遵循 `.ai/README.md` 的进场协议。
 
-- 需求文档工作(新建/定稿)→ requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
-- 记忆更新 → 节点式(完成任务节点立即写),协议见 `.ai/skills/memory-update.md`
-- 反驳检查 → critic skill 或定稿流程内强制触发;同上下文自检,刻意抵制自我辩护(见 `.ai/skills/critic.md` 纪律)
+- 0→1 项目/首次架构基线/重大重构 → project-inception skill,产物在 `docs/architecture/`;普通功能不要重复触发
+- 需求 what/why 与外部行为定稿 → requirements-flow skill,产物在 `docs/requirements/vX.Y.Z/{draft,final}/`
+- M/L 级功能 how 与技术接口 → feature-design skill,产物在 `docs/design/vX.Y.Z/`;S 级可直接实现
+- 交付前 → delivery-readiness skill,按风险验证契约、测试、迁移、回滚、性能与可观测性
+- 记忆更新 → 只在可验收工程节点、关键决策、状态变化或会话切换时写
+- 反驳检查 → S 级精简自检;M/L 级或用户明确要求时用 critic skill
 
 ## 与 superpowers 的编排(未安装则忽略本节)
 
-1. 需求定稿(what/why)走 requirements-flow;实现设计(how)走 brainstorming,以 `docs/requirements/*/final/*.md` 为输入
-2. code review 走 superpowers 流程,叠加 `.ai/skills/code-review.md` 的项目检查项
+1. final 需求已经确认 what/why,不要用 brainstorming 重复澄清目标与范围
+2. S 级跳过 brainstorming/writing-plans;M 级只对未决高影响 how 选择性使用;L 级可使用完整流程
+3. 所有 Superpowers 结论必须回写 `docs/design/`,临时 spec/plan 不是唯一事实源
+4. code review 使用适合风险等级的流程,叠加 `.ai/skills/code-review.md` 的项目检查项
 
 ## 项目信息
 

package/templates/common/.ai/README.md

@@ -11,8 +11,9 @@
 
 ## 目录
 
+- `ai-memory.json` — 框架版本、Schema、启用工具、文件所有权与生成基线哈希;供安全升级预检使用
 - `memory/` — 记忆层:MEMORY.md 索引、project-state 全景、session-log 流水、user-profile/feedback 用户级记忆、features/ 功能档案
-- `skills/` — 方法论层:requirements-flow、architecture、code-review、critic、memory-update
+- `skills/` — 方法论层:project-inception、requirements-flow、feature-design、delivery-readiness、architecture、code-review、critic、memory-update
 
 ## 与工具专属配置的关系
 

package/templates/common/.ai/memory/project-state.md

@@ -11,7 +11,7 @@
 
 ## 需求进度
 
-| 版本 | 需求 | 状态(draft/finalized/in-progress/done) | 备注 |
+| 版本 | 需求 | 状态(draft/finalized/designed/in-progress/done) | 备注 |
 |---|---|---|---|
 
 ## 已知遗留问题

package/templates/common/.ai/memory/session-log.md

@@ -1,6 +1,6 @@
 # Session 日志
 
-> 高频追加文件:每完成一个任务节点/关键决策,带时间戳追加一条;只增不改。
+> 工程节点追加文件:完成可独立验收的功能/阶段、做出关键决策或会话切换时追加;细碎代码步骤合并记录,只增不改。
 > 超过约 200 行时,把旧条目压缩进 project-state.md 的「归档的 session 摘要」。
 > 跨工具(Claude Code ↔ Codex)切换前,必须确认本文件已落盘并 commit。
 

package/templates/common/.ai/skills/architecture.md

@@ -1,22 +1,32 @@
-# 架构方法论(语言无关)
+# 架构方法论（语言无关）
 
 ## 模块边界
 
-- 每个模块用一句话说清职责;说不清 = 边界有问题
-- 模块间只通过显式接口通信;不看内部实现也能正确使用
-- 依赖单向:上层可依赖下层,禁止反向依赖与循环依赖
+- 每个模块用一句话说明职责；无法说明通常意味着边界混乱。
+- 模块间只通过显式接口通信，依赖保持单向并避免循环。
+- 只为真实变化或隔离需求建立抽象，不为未知未来预留扩展点。
 
-## 接口契约格式(定稿时写入 final/*.md 的「接口契约」章节)
+## 两层契约
 
-每个接口写清:
+### 外部行为契约（需求阶段）
 
-- **名称与语义**:做什么,明确不做什么
-- **输入**:参数、类型、边界值约定
-- **输出**:返回结构、错误路径(每种失败如何表达给调用方)
-- **幂等/并发**:重复调用的后果,是否需要去重或加锁
-- **兼容**:后续变更如何不破坏既有调用方
+记录参与者、输入、输出、失败表达、副作用、兼容性和可观察验收结果，不固定内部实现。
 
-## 跨技术栈落地
+### 技术边界契约（how 阶段）
 
-本文件只写原则。具体项目的模块清单、依赖层级、数据规范写在
-`.ai/memory/project-state.md` 或 `features/` 对应档案里,由 agent 按本原则裁剪到当前技术栈。
+仅为跨模块、服务、进程、持久化或事件边界的接口写清：
+
+- 名称、职责与明确不负责的内容
+- 输入输出及类型/模式
+- 错误、超时、重试与降级
+- 状态变化、事务边界、一致性、幂等和并发
+- 版本、兼容和迁移策略
+- 可观测信号与契约测试
+
+私有实现细节不需要逐函数建档。
+
+## 项目基线与功能增量
+
+- `docs/architecture/` 保存系统、数据、质量属性和部署基线。
+- `docs/design/` 只记录功能相对基线的 how 与增量影响。
+- 实现完成后的稳定决策摘要进入 `.ai/memory/features/`，不要复制整份设计文档。

package/templates/common/.ai/skills/code-review.md

@@ -2,7 +2,7 @@
 
 > 不注册为 skill;供 superpowers 的 code review 流程作为附加检查项引用。
 
-- **契约一致**:实现与 `final/*.md` 的接口契约、验收标准逐条对照
+- **契约一致**:实现与 `final/*.md` 的外部行为契约、验收标准及适用的 `docs/design/` 技术接口逐条对照
 - **错误路径**:失败表达与契约声明一致,没有吞掉错误
 - **记忆同步**:功能行为变化已更新 `features/` 对应档案
 - **范围**:未引入需求「不做什么」里排除的内容

package/templates/common/.ai/skills/critic.md

@@ -17,5 +17,6 @@
 
 - 主 agent 必须逐条回应「接受并修改」或「给出理由反驳」,不允许沉默跳过
 - 全部处理完毕才算通过
-- Claude Code 侧:由 critic subagent 独立上下文执行,只给文档路径,不给对话历史
-- Codex 侧:同上下文自检,刻意抵制为自己刚写内容辩护的倾向
+- S 级低风险需求可在同上下文按四类清单做一次精简自检,不启动独立 agent
+- M/L 级需求、架构基线和高影响技术设计优先由独立 critic 执行,只给文档路径与本方法,不给对话历史
+- 工具不支持独立上下文时才降级为同上下文自检,并刻意抵制为自己刚写内容辩护

package/templates/common/.ai/skills/delivery-readiness.md

@@ -0,0 +1,32 @@
+# 交付就绪检查
+
+在功能准备合并、发布或部署时使用。它是基于证据的轻量检查门，不重新做需求澄清或技术设计。
+
+## 深度路由
+
+- S：验证外部契约、相关测试和无意副作用；本地功能不强制生成独立报告。
+- M：检查适用的数据、性能、可观测性、部署和回滚影响，并把证据写回设计文档。
+- L：完整检查质量属性、迁移/回滚、生产验证和运行保障；阻塞项清零前不得标记就绪。
+
+## 流程
+
+1. 读取 final 需求、适用的技术设计、架构基线和代码差异；不复制这些内容。
+2. 逐条验证外部行为契约与验收标准，记录命令、测试或其他证据。
+3. 只检查适用项；不适用必须写原因，不能静默跳过。
+4. 将结果写入 `docs/design/...` 的“交付验证”章节；S 级无设计文档时记入 session-log。
+5. 输出明确结论：`ready`、`conditional` 或 `not-ready`，并列出阻塞项。
+
+## 检查面
+
+| 检查面 | 必须回答的问题 |
+|---|---|
+| 契约与测试 | 外部契约、技术接口和失败路径是否有验证证据？ |
+| 数据 | Schema/数据迁移顺序、兼容、校验和回滚是否可执行？ |
+| 部署 | 配置、密钥、制品、发布顺序、健康检查和回滚是否明确？ |
+| 性能与容量 | 受影响预算是否验证，瓶颈与扩容触发条件是否仍成立？ |
+| 可观测性 | 日志、关联 ID、指标、错误上报和告警能否发现并定位失败？ |
+| 可靠性 | 超时、重试、幂等、降级、备份和恢复是否符合风险等级？ |
+| 安全 | 权限、敏感数据、输入边界和依赖风险是否已检查？ |
+| 运行交接 | 谁能判断发布成功、何时停止或回滚、故障如何处置？ |
+
+不要仅凭“代码已完成”判定 ready，也不要为 S 级本地改动强制搭建生产级设施。

package/templates/common/.ai/skills/feature-design.md

@@ -0,0 +1,33 @@
+# 功能技术设计（how）
+
+输入：已定稿需求、相关架构基线和功能记忆。输出：可直接实施的技术设计，不重新讨论已确认的 what/why。
+
+## 适用性
+
+- S 级需求默认不生成完整设计；只在实现中遵循外部契约并测试。
+- M 级生成精简设计，聚焦实际变化。
+- L 级先更新 `docs/architecture/` 基线，再完成设计和聚焦 critic。
+
+## 流程
+
+1. 读取 `final/<需求名>.md` 的实现交接，以及相关 `docs/architecture/`、源码和 feature 记忆。
+2. 若需求存在矛盾或阻塞开放问题，退回 requirements-flow；不要用实现假设偷偷补需求。
+3. 在 `docs/design/vX.Y.Z/<需求名>.md` 按模板形成设计，只填写适用章节，不涉及也要简述原因。
+4. 为真实边界定义技术接口契约；不要为所有私有函数写文档。
+5. 记录数据模型和质量属性相对项目基线的增量，不复制整份基线。
+6. 检查设计是否可实施、可测试、可迁移、可回滚、可观测。
+7. M 级做一次精简自检；L 级按 critic 方法做独立或聚焦审查。
+8. 更新 `project-state.md` 为 `designed`，实现计划只引用本设计，不重新生成同义 spec。
+
+## Superpowers 路由
+
+- S：跳过 brainstorming 和 writing-plans。
+- M：仅当存在无法由基线和约束解决的高影响 how 选择时，使用针对性 brainstorming；设计已可实施时跳过完整 writing-plans。
+- L：可使用 brainstorming 比较重大方案，并用 writing-plans 拆实施阶段；必须把结论回写到本设计，Superpowers 临时产物不是唯一事实源。
+
+## 完成门槛
+
+- 模块职责、依赖和关键流程明确。
+- 跨边界接口、错误、状态、一致性和兼容策略明确。
+- 数据、性能、可观测性、容量/功能扩展、可靠性、安全、部署影响均已判断。
+- 验证、迁移和回滚可执行；假设有验证方式。

package/templates/common/.ai/skills/memory-update.md

@@ -1,24 +1,29 @@
-# 记忆更新协议(节点式)
+# 记忆更新协议（工程节点）
 
 ## 触发时机
 
-1. **完成一个任务节点 / 做出关键决策 → 立即写**,不攒到会话结束(主路径)
-2. 用户说「更新记忆」或 /update-memory
-3. 会话收尾、上下文即将压缩
-4. 需求状态变化(requirements-flow 第 5 步联动)
+只在信息对后续会话仍有价值时写入：
+
+1. 完成一个可独立验收的功能、阶段或发布节点。
+2. 做出会约束后续实现的关键决策，或推翻已有决策。
+3. 需求/设计/实现/交付状态变化。
+4. 发现需要跨会话保留的风险、故障原因或踩坑。
+5. 会话中断、上下文压缩或跨工具切换前。
+
+不要因为写了一个测试、修改一个私有函数、执行一次命令或完成细碎 plan item 单独更新记忆。
 
 ## 写入路由
 
 | 内容 | 去处 |
 |---|---|
-| 进展流水(做到哪/下一步/踩坑) | `session-log.md` 带时间戳追加 |
-| 需求/里程碑状态变化 | `project-state.md` 对应表格行 |
-| 功能设计决策、契约变更 | `features/<名>.md` |
-| 新增记忆文件 | `MEMORY.md` 加索引行 |
+| 工程节点、当前进度、下一步、阻塞 | `session-log.md` 追加 |
+| 需求、设计、里程碑或交付状态 | `project-state.md` 对应行 |
+| 稳定功能决策与契约变化摘要 | `features/<名>.md` |
+| 新增记忆文件 | `MEMORY.md` 加索引 |
 
-## 硬性约束
+## 约束
 
-- 写前先读目标文件
-- 只增量追加,不重构既有格式与历史条目
-- session-log 超约 200 行:把旧条目压缩进 project-state.md 的归档章节
-- 跨工具切换前确认 session-log 已落盘;记忆变更随代码一起 commit
+- 写前读取目标文件，只记录增量和新事实，不复制需求/设计/测试输出。
+- 将同一工程节点内的相关小步骤合并为一条，避免流水噪声。
+- session-log 超约 200 行时，把旧条目压缩进 project-state 归档章节。
+- 跨工具切换前确认关键状态已落盘；记忆变更随对应代码或文档一起 commit。

package/templates/common/.ai/skills/project-inception.md

@@ -0,0 +1,33 @@
+# 项目工程基线（0→1）
+
+适用：新项目、首次补建架构基线，或会改变系统边界/数据所有权/部署拓扑的重大重构。普通功能迭代不要重复执行。
+
+## 原则
+
+- 只规定语言无关的工程问题；语言、框架、数据库和云平台是项目答案，不是流程前提。
+- 先记录事实，再记录假设；每个关键假设必须有验证方式或触发复审的条件。
+- 采用满足近期目标的最小架构，禁止用“未来可能扩展”代替具体负载或变化场景。
+- 已有项目以现状盘点补建基线，不为套模板而重做架构。
+- 默认不启动 Superpowers 全套流程；仅在存在多个高影响方案且无法用现有约束决策时，选择性使用 brainstorming。
+
+## 工作流
+
+1. 读取项目目标、现有代码/文档和 `.ai/memory/project-state.md`。
+2. 判断是 0→1、新增基线还是重大重构；不适用则停止并转入需求或功能设计流程。
+3. 只询问会改变架构方向的阻塞信息；非阻塞信息采用保守假设并明确标记。
+4. 按 `docs/architecture/` 的四份模板建立或增量更新工程基线：
+   - `system-context.md`：边界、参与者、模块和关键流程。
+   - `data-model.md`：实体、关系、所有权、生命周期、一致性和迁移。
+   - `quality-attributes.md`：性能、可观测性、扩展性、可靠性、安全、维护性和成本。
+   - `deployment.md`：环境、拓扑、配置、发布、迁移、回滚和运行保障。
+5. 检查四份文档之间是否矛盾；高风险或生产级项目按 `.ai/skills/critic.md` 做一次聚焦审查。
+6. 将确定的技术栈、部署基线和关键风险更新到 `project-state.md`，并在 session-log 记录节点。
+
+## 完成门槛
+
+- 系统内外边界、数据所有权和部署单元明确。
+- 关键质量属性使用“场景 / 条件 / 响应 / 指标 / 验证”表达，而不是形容词。
+- 监控覆盖已知故障；可观测性足以关联请求或任务并定位未知故障。
+- 容量扩展绑定负载场景；功能扩展绑定变化场景。
+- 发布、数据迁移和回滚至少有可执行方向。
+- 所有未知项明确标为假设、风险或开放问题，不伪装成已确认决策。

package/templates/common/.ai/skills/requirements-flow.md

@@ -1,23 +1,38 @@
-# 需求定稿流程(draft → final)
+# 需求定稿流程（draft → final）
 
-触发:用户要求新建/定稿需求,或 /new-requirement、/finalize-requirement。
+本流程只确定 what/why、范围、外部行为和验收标准，不决定模块、存储、框架等 how。技术设计交给 `feature-design`。
 
-## 新建(new)
+## 新建
 
-1. 确认目标版本目录 `docs/requirements/vX.Y.Z/`(不存在则创建 draft/ 与 final/)
-2. 在 `draft/<需求名>.md` 生成骨架:背景 / 想要什么 / 不确定的点
-3. 在 `.ai/memory/project-state.md` 需求进度表登记一行(状态 draft)
+1. 确认版本目录 `docs/requirements/vX.Y.Z/`，不存在则创建 `draft/` 与 `final/`。
+2. 在 `draft/<需求名>.md` 记录：背景 / 想要什么 / 不确定的点。
+3. 在 `project-state.md` 需求进度表登记状态 `draft`。
 
-## 定稿(finalize)
+## 定稿
 
-1. 读 `draft/<需求名>.md`
-2. 逐个澄清模糊点:一次只问一个问题,优先选择题
-3. 按固定结构成稿:**目标 / 范围(必须含「不做什么」)/ 接口契约(格式见 architecture.md)/ 验收标准 / 开放问题**
-4. 强制 critic 门:按 `critic.md` 检查,逐条回应完毕才可写入 `final/<需求名>.md`
-5. 联动记忆:project-state 状态改 finalized;`features/<需求名>.md` 建档登记契约要点;MEMORY.md 加索引行
-6. 需求文档与记忆变更一起 commit
+1. 读取 draft、相关功能记忆和已有外部契约。
+2. 只澄清会改变目标、范围、用户可见行为或验收结果的问题；实现选择留给技术设计。
+3. 按固定结构形成候选稿：
+   - **目标**
+   - **范围**：包含与不做什么
+   - **外部行为契约**：参与者、输入、输出、失败表达、副作用、兼容性
+   - **验收标准**：可观察、可验证
+   - **开放问题**：不得隐藏阻塞项
+   - **实现交接**：已确认决策、how 阶段待决定项、禁止重新讨论项、初步风险等级
+4. 先给出初步风险等级，再按 `.ai/skills/critic.md` 审查需求完整性：S 级做精简同上下文自检，M/L 级使用独立 critic（工具支持时）；逐条处理后才写 `final/<需求名>.md`。
+5. 按下方路由选择下一步，不在本流程中启动重复 brainstorming。
+6. 更新 `project-state.md` 为 `finalized`；在 `features/<需求名>.md` 记录外部契约与关键决策，并更新 MEMORY 索引。
 
-## 与 superpowers 的衔接
+## 风险路由
 
-实现阶段由 brainstorming/writing-plans 以 `final/<需求名>.md` 为输入。
-本流程只产出需求(what/why),不做实现设计(how)。
+| 等级 | 判断 | 下一步 |
+|---|---|---|
+| S | 局部、可逆，不跨模块/数据/部署边界，验收明确 | 可直接实现并测试；不生成完整技术设计 |
+| M | 跨多个模块，或改变数据、公共接口、运行行为 | 执行 `feature-design`，生成精简技术设计 |
+| L | 改变系统边界、数据所有权、部署拓扑，或安全/迁移/可用性风险高 | 先更新项目基线，再执行完整 `feature-design`；只对未决高影响方案选择性使用 Superpowers |
+
+拿不准时选高一级，并在实现交接中写明原因。风险等级决定流程深度，不代表需求价值。
+
+## 外部行为契约边界
+
+只写调用方或用户可观察的承诺。不要在 final 需求中固定类、函数、表结构、队列、框架或部署组件，除非它们本身就是业务约束。

package/templates/common/docs/architecture/data-model.md

@@ -0,0 +1,43 @@
+# 数据模型基线
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 先描述领域与数据语义；物理表、文档或消息结构只在已经确定时记录。
+
+## 适用性
+
+- 是否持久化数据：
+- 数据来源与权威源：
+
+## 核心实体
+
+| 实体 | 业务含义 | 标识与唯一性 | 所有者 | 生命周期 |
+|---|---|---|---|---|
+
+## 关系与约束
+
+- 实体关系：
+- 完整性约束：
+- 状态转换：
+
+## 一致性与并发
+
+- 一致性要求：
+- 并发冲突策略：
+- 幂等与去重：
+
+## 敏感数据与保留
+
+- 数据分类：
+- 访问与审计：
+- 保留、归档与删除：
+
+## 迁移与兼容
+
+- 初始化/迁移方向：
+- 前后兼容：
+- 回滚与校验：
+
+## 假设与开放问题
+
+- （每项附验证方式或复审条件）

package/templates/common/docs/architecture/deployment.md

@@ -0,0 +1,40 @@
+# 部署与运行基线
+
+> 项目：{{projectName}}
+> 技术栈：{{techStack}}
+> 最后更新：{{date}}
+
+## 环境与拓扑
+
+| 环境 | 部署单元 | 基础设施/外部依赖 | 状态位置 |
+|---|---|---|---|
+
+## 配置、密钥与权限
+
+- 配置来源与分环境策略：
+- 密钥存储与轮换：
+- 运行身份与最小权限：
+
+## 发布流程
+
+1. 构建与制品：
+2. 发布与验证：
+3. 数据迁移顺序：
+4. 回滚条件与步骤：
+
+## 运行保障
+
+- 存活与就绪判定：
+- 日志、指标、追踪和错误上报入口：
+- 告警与值守方式：
+- 备份、恢复目标与演练：
+
+## 容量与成本
+
+- 初始容量：
+- 扩缩容方式与触发条件：
+- 成本边界：
+
+## 单点、风险与开放问题
+
+- （每项附缓解措施或验证方式）

package/templates/common/docs/architecture/quality-attributes.md

@@ -0,0 +1,50 @@
+# 质量属性基线
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 用可验证场景代替“高性能、可扩展、稳定”等形容词。
+
+## 负载与容量假设
+
+| 指标 | 当前/初始值 | 目标或上限 | 验证方式 | 复审触发条件 |
+|---|---|---|---|---|
+| 用户/租户数 | | | | |
+| 峰值吞吐 | | | | |
+| 数据规模与增长 | | | | |
+
+## 质量属性场景
+
+| 属性 | 场景与条件 | 系统响应 | 可量化指标 | 验证方式 |
+|---|---|---|---|---|
+| 性能 | | | | |
+| 可用性/可靠性 | | | | |
+| 安全性 | | | | |
+| 可维护性 | | | | |
+| 成本 | | | | |
+
+## 可观测性最低基线
+
+- 健康/就绪检查：
+- 结构化日志与关联 ID：
+- 核心流量、错误、耗时和饱和度指标：
+- 错误上报与部署版本：
+- 追踪适用条件：
+- 告警与运行手册：
+
+## 容量扩展性
+
+- 负载增长场景：
+- 当前瓶颈假设：
+- 水平/垂直扩容方向：
+- 状态、分区与背压：
+- 扩容触发指标：
+
+## 功能可扩展性
+
+- 预期变化场景：
+- 需要稳定的边界与兼容策略：
+- 明确不预留的抽象：
+
+## 假设与待验证项
+
+- （每项写明负责人、方式或复审条件）

package/templates/common/docs/architecture/system-context.md

@@ -0,0 +1,35 @@
+# 系统上下文
+
+> 项目：{{projectName}}
+> 最后更新：{{date}}
+> 状态：待建立基线
+
+## 目标与非目标
+
+- 目标：
+- 非目标：
+
+## 参与者与外部系统
+
+| 参与者/系统 | 关系 | 输入/输出 | 约束 |
+|---|---|---|---|
+
+## 系统边界
+
+- 系统负责：
+- 系统不负责：
+- 信任边界：
+
+## 模块与职责
+
+| 模块/部署单元 | 单一职责 | 依赖 | 状态归属 |
+|---|---|---|---|
+
+## 关键流程
+
+1. （写出跨边界的主路径和失败路径）
+
+## 决策、假设与风险
+
+| 类型（决策/假设/风险） | 内容 | 依据或验证方式 | 复审触发条件 |
+|---|---|---|---|

package/templates/common/docs/design/README.md

@@ -0,0 +1,22 @@
+# 功能技术设计目录
+
+- 按版本存放：`vX.Y.Z/<需求名>.md`。
+- 输入是 `docs/requirements/.../final/` 的需求定稿和 `docs/architecture/` 项目基线。
+- S 级需求可不生成完整设计；M/L 级按 `.ai/skills/feature-design.md` 执行。
+- 只记录 how 和相对项目基线的增量，不复述已确认的需求或整份架构基线。
+
+## 设计结构
+
+1. 目标与约束引用
+2. 风险等级与理由
+3. 现状及影响范围
+4. 模块、职责与依赖
+5. 技术接口契约
+6. 数据模型增量
+7. 核心流程与状态转换
+8. 错误、并发、幂等与兼容
+9. 质量属性增量
+10. 部署、迁移与回滚
+11. 测试与验证
+12. 假设和开放问题
+13. 交付验证（ready/conditional/not-ready、证据与阻塞项）

package/templates/common/docs/requirements/README.md

@@ -2,5 +2,6 @@
 
 - 每个迭代版本一个目录:`vX.Y.Z/`
 - `draft/` — 人工粗稿,自由格式,想到哪写到哪
-- `final/` — AI 协作定稿,固定结构:目标 / 范围 / 接口契约 / 验收标准 / 开放问题
+- `final/` — AI 协作定稿,固定结构:目标 / 范围 / 外部行为契约 / 验收标准 / 开放问题 / 实现交接
 - 定稿流程见 `.ai/skills/requirements-flow.md`(/new-requirement、/finalize-requirement)
+- how 阶段技术接口与数据/质量属性增量见 `.ai/skills/feature-design.md` 和 `docs/design/`