@stormhwdev/claude-config 1.0.0

package/templates/PRD.md.tpl

@@ -0,0 +1,109 @@
+# 产品需求文档（PRD）
+
+> 项目名称：{{PROJECT_NAME}}
+> 版本：v1.0
+> 作者：Product Manager
+> 日期：{{DATE}}
+> 状态：草稿 / 待确认 / 已确认
+
+---
+
+## 1. 概述
+
+### 1.1 项目背景
+
+<!-- 描述项目的背景、业务动机 -->
+
+### 1.2 目标用户
+
+<!-- 目标用户画像和使用场景 -->
+
+### 1.3 核心目标
+
+<!-- 项目要解决的核心问题和达成的目标 -->
+
+---
+
+## 2. 用户故事
+
+<!-- 格式：作为<角色>，我希望<功能>，以便<价值> -->
+<!-- 按优先级排序 -->
+
+| 编号 | 优先级 | 用户故事 |
+|------|--------|----------|
+| US-001 | P0 | 作为...，我希望...，以便... |
+| US-002 | P0 | 作为...，我希望...，以便... |
+| US-003 | P1 | 作为...，我希望...，以便... |
+
+---
+
+## 3. 功能需求总览
+
+<!-- 每条功能需求的完整定义在独立文件 docs/prd/FR-NNN-<name>.md 中。本节仅作索引。 -->
+
+| 编号 | 功能名称 | 优先级 | 所属模块 | 状态 | 明细文件 |
+|------|----------|--------|----------|------|----------|
+| FR-001 | {{功能名称}} | P0 | {{模块}} | 待开发 | [FR-001](prd/FR-001-{{name}}.md) |
+| FR-002 | {{功能名称}} | P0 | {{模块}} | 待开发 | [FR-002](prd/FR-002-{{name}}.md) |
+
+**状态说明**：待开发 / 开发中 / 已完成 / 已废弃
+
+---
+
+## 4. 非功能需求
+
+### 4.1 性能要求
+
+- 接口响应时间：
+- 并发处理能力：
+- 数据处理量：
+
+### 4.2 安全要求
+
+- 认证方式：
+- 数据加密：
+- 权限控制：
+
+### 4.3 兼容性要求
+
+- 支持平台：
+- 浏览器版本：
+- 最低配置：
+
+---
+
+## 5. 页面/交互需求
+
+### 5.1 页面列表
+
+| 页面 | 功能描述 | 对应需求 |
+|------|----------|----------|
+| | | |
+
+### 5.2 页面跳转关系
+
+<!-- 描述页面间的导航和跳转逻辑 -->
+
+### 5.3 关键交互流程
+
+<!-- 描述核心用户操作流程 -->
+
+---
+
+## 6. 验收标准摘要
+
+<!-- 完整验收条件在各功能明细文件的「验收标准」节中。本节仅作摘要索引。 -->
+
+| 编号 | 对应需求 | 验收条件摘要 |
+|------|----------|-------------|
+| AC-001 | FR-001 | |
+| AC-002 | FR-002 | |
+
+---
+
+## 7. 优先级与排期建议
+
+- **P0（必须实现）**：
+- **P1（应该实现）**：
+- **P2（可后续迭代）**：
+

package/templates/changelog.md.tpl

@@ -0,0 +1,78 @@
+# {{DATE}} {{需求概要}}
+
+> 模块：{{MODULE_NAME}}
+> 关联需求：FR-XXX
+> 作者：{{AUTHOR}}
+> 日期：{{DATE}}
+
+---
+
+## 1. 变更背景
+
+<!-- 为什么需要这次变更？业务动机、用户反馈、技术债务等 -->
+
+---
+
+## 2. 变更范围
+
+### 涉及的规范文档更新
+
+| 文档 | 变更类型 | 说明 |
+|------|----------|------|
+| `contracts.md` | 新增/修改/删除 | |
+| `design-overview.md` | 更新 | |
+| `module-dependencies.md` | 更新 | |
+
+### 影响的模块
+
+| 模块 | 影响方式 | 是否需要适配 |
+|------|----------|-------------|
+| | 接口变更/事件变更/无影响 | |
+
+---
+
+## 3. 设计方案
+
+<!-- 本次变更的技术设计方案，包括：
+- 新增/修改的实体、值对象、事件
+- 接口设计（如有新增或变更）
+- 数据模型变更（如有）
+- 业务流程调整
+-->
+
+---
+
+## 4. 实施细节
+
+<!-- 具体的实施步骤和关键代码变更说明 -->
+
+### 4.1 代码变更
+
+| 文件路径 | 变更类型 | 说明 |
+|----------|----------|------|
+| | 新增/修改/删除 | |
+
+### 4.2 数据库迁移（如有）
+
+<!-- 迁移文件路径和说明 -->
+
+### 4.3 配置变更（如有）
+
+<!-- 环境变量、配置项的新增或修改 -->
+
+---
+
+## 5. 测试覆盖
+
+| 测试类型 | 测试文件 | 覆盖场景 |
+|----------|----------|----------|
+| 单元测试 | | |
+| 集成测试 | | |
+
+---
+
+## 6. 关键决策与备注
+
+<!-- 记录本次变更涉及的关键决策（架构选型、技术方案抉择、设计取舍等），以及其他需要记录的信息。
+     关键决策应包含：决策内容、理由、替代方案对比、影响范围。
+     此处是项目关键决策的唯一归档位置，确保未来 agent 可查阅历史决策。 -->

package/templates/contracts.md.tpl

@@ -0,0 +1,112 @@
+# 模块接口契约文档
+
+> 模块名称：{{MODULE_NAME}}
+> 版本：v1.0
+> 最后更新：{{DATE}}
+
+---
+
+## 1. Service 接口（暴露给其他模块）
+
+### {{ServiceName}}Service
+
+#### `methodName(params): ReturnType`
+
+- **描述**：
+- **参数**：
+  ```typescript
+  interface MethodParams {
+    // 参数定义
+  }
+  ```
+- **返回值**：
+  ```typescript
+  interface MethodResult {
+    // 返回值定义
+  }
+  ```
+- **异常**：
+  - `NotFoundError` — 描述
+  - `ValidationError` — 描述
+- **调用方**：{{调用方模块列表}}
+
+---
+
+## 2. Controller 接口（暴露给前端的 HTTP API）
+
+### `METHOD /api/v1/resource`
+
+- **描述**：
+- **认证**：是否需要登录
+- **请求参数**：
+  ```typescript
+  // Query / Path / Body
+  interface RequestBody {
+    // 请求体定义
+  }
+  ```
+- **成功响应**（200）：
+  ```typescript
+  interface SuccessResponse {
+    code: 0;
+    data: {
+      // 响应数据定义
+    };
+  }
+  ```
+- **错误响应**：
+  | HTTP 状态码 | 错误码 | 描述 |
+  |-------------|--------|------|
+  | 400 | INVALID_PARAMS | 参数错误 |
+  | 404 | NOT_FOUND | 资源不存在 |
+
+---
+
+## 3. Events（关键领域事件）
+
+### `{{ModuleName}}.{{EventName}}`
+
+- **触发条件**：
+- **负载（Payload）**：
+  ```typescript
+  interface EventPayload {
+    // 事件数据定义
+  }
+  ```
+- **订阅方**：{{订阅方模块列表}}
+- **处理说明**：
+
+---
+
+## 4. 依赖的外部接口
+
+### 依赖模块：{{ModuleName}}
+
+| 接口 | 用途 | 是否可选 |
+|------|------|----------|
+| `ServiceName.methodName()` | 描述 | 是/否 |
+
+### 订阅的外部事件
+
+| 事件 | 来源模块 | 处理说明 |
+|------|----------|----------|
+| `Module.EventName` | {{ModuleName}} | 描述 |
+
+---
+
+## 5. 跨服务接口（仅多服务项目）
+
+<!-- 单服务项目删除本节。多服务项目在此记录与其他服务的网络通信接口。 -->
+
+### 对外暴露给其他服务的接口
+
+| 接口路径/方法 | 协议 | 调用方服务 | 用途 | 认证方式 |
+|--------------|------|-----------|------|----------|
+| | HTTP/gRPC | | | |
+
+### 调用其他服务的接口
+
+| 目标服务 | 接口路径/方法 | 协议 | 用途 | 超时设置 | 失败策略 |
+|----------|--------------|------|------|----------|----------|
+| | | HTTP/gRPC | | | 重试/熔断/降级 |
+

package/templates/design-overview.md.tpl

@@ -0,0 +1,83 @@
+# 模块设计概览
+
+> 模块名称：{{MODULE_NAME}}
+> 所属服务：{{SERVICE_NAME}}（多服务项目填写；单服务项目删除此行）
+> 版本：v1.0
+> 最后更新：{{DATE}}
+
+---
+
+## 1. 模块职责
+
+<!-- 用 1-2 句话描述模块的核心职责 -->
+
+---
+
+## 2. 领域模型
+
+### 2.1 聚合根（Aggregate Root）
+
+| 聚合根 | 描述 | 关键属性 |
+|--------|------|----------|
+| | | |
+
+### 2.2 实体（Entity）
+
+| 实体 | 所属聚合 | 描述 |
+|------|----------|------|
+| | | |
+
+### 2.3 值对象（Value Object）
+
+| 值对象 | 描述 | 属性 |
+|--------|------|------|
+| | | |
+
+---
+
+## 3. 功能清单
+
+| 编号 | 功能名称 | 描述 | 详细设计文档 |
+|------|----------|------|--------------|
+| F-001 | | | `feature-xxx.md` |
+| F-002 | | | `feature-xxx.md` |
+
+---
+
+## 4. 目录结构
+
+<!-- 路径说明：单服务项目使用 src/<module>/；多服务项目按 topology.md 路径映射表替换为实际路径。 -->
+
+```
+{{MODULE_PATH}}/
+├── domain/
+│   ├── entities/
+│   ├── value-objects/
+│   ├── events/
+│   └── services/
+├── application/
+│   └── services/
+├── infrastructure/
+│   └── repositories/
+├── interfaces/
+│   ├── controllers/
+│   └── subscribers/
+└── __tests__/
+```
+
+---
+
+## 5. 依赖关系
+
+### 被依赖方（本模块提供的能力）
+
+| 调用方模块 | 使用的接口/事件 |
+|------------|-----------------|
+| | |
+
+### 依赖方（本模块需要的外部能力）
+
+| 被依赖模块 | 使用的接口/事件 |
+|------------|-----------------|
+| | |
+

package/templates/feature.md.tpl

@@ -0,0 +1,94 @@
+# 功能详细设计文档
+
+> 模块：{{MODULE_NAME}}
+> 所属服务：{{SERVICE_NAME}}（多服务项目填写；单服务项目删除此行）
+> 功能：{{FEATURE_NAME}}
+> 编号：F-XXX
+> 对应需求：FR-XXX
+> 最后更新：{{DATE}}
+
+---
+
+## 1. 功能描述
+
+<!-- 功能的详细描述，包含业务背景 -->
+
+---
+
+## 2. 接口定义
+
+### 2.1 对外接口
+
+<!-- 本功能涉及的 Service / Controller / Event 接口 -->
+<!-- 详细定义请参考 contracts.md -->
+
+### 2.2 内部接口
+
+<!-- 本功能内部的关键方法签名 -->
+
+---
+
+## 3. 业务规则
+
+| 编号 | 规则描述 | 触发条件 |
+|------|----------|----------|
+| BR-001 | | |
+
+---
+
+## 4. 数据模型
+
+<!-- 本功能涉及的数据结构、数据库表（如有） -->
+
+```typescript
+// 关键数据结构
+```
+
+---
+
+## 5. 流程设计
+
+<!-- 核心业务流程描述，可用文字或伪代码 -->
+
+```
+1. 接收请求
+2. 参数校验
+3. 业务逻辑处理
+4. 持久化
+5. 发布领域事件（如有）
+6. 返回结果
+```
+
+---
+
+## 6. 异常处理
+
+| 异常场景 | 处理方式 | 错误码 |
+|----------|----------|--------|
+| | | |
+
+---
+
+## 7. 测试要点
+
+| 测试场景 | 输入 | 预期输出 | 类型 |
+|----------|------|----------|------|
+| 正常路径 | | | Unit |
+| 边界条件 | | | Unit |
+| 异常情况 | | | Unit |
+
+---
+
+## 8. 代码位置
+
+<!-- 实现后填写，方便后续维护时快速定位 -->
+<!-- 路径说明：单服务项目使用 src/<module>/；多服务项目按 topology.md 路径映射表替换为实际路径。 -->
+
+| 层 | 文件路径 | 说明 |
+|----|----------|------|
+| Domain | `{{MODULE_PATH}}/domain/...` | |
+| Application | `{{MODULE_PATH}}/application/...` | |
+| Infrastructure | `{{MODULE_PATH}}/infrastructure/...` | |
+| Interface | `{{MODULE_PATH}}/interfaces/...` | |
+| Test | `{{MODULE_PATH}}/__tests__/...` | |
+

package/templates/lifecycle-archive-index.md.tpl

@@ -0,0 +1,12 @@
+# 迭代归档索引
+
+> 最后更新：{{DATE}}
+
+<!--
+  记录已完成迭代的归档索引。分支合入主分支时，在此追加归档记录。
+  归档文件为只读，不再修改。
+-->
+
+| 编号 | 日期范围 | 迭代目标 | 原分支名称 | 归档路径 |
+|------|----------|----------|-----------|----------|
+| | | | | |

package/templates/lifecycle.md.tpl

@@ -0,0 +1,116 @@
+# 研发生命周期跟踪
+
+> 分支名称：{{BRANCH_NAME}}
+> 需求规模：{{SCALE}}（基线建档 / 小型改造 / 大型改造）
+> 迭代目标：{{ITERATION_GOAL}}
+> 创建日期：{{DATE}}
+> 最后更新：{{DATE}}
+
+<!--
+  本文件为分支级过程文件，仅跟踪当前分支的研发进度。
+  项目拓扑信息请参见 docs/topology.md。
+  分支合入主分支后，本文件归档或删除。
+-->
+
+---
+
+## 1. 阶段总览
+
+| Phase | 阶段名称 | 状态 | 人工确认 | 开始时间 | 完成时间 | 备注 |
+|-------|----------|------|----------|----------|----------|------|
+| 0 | 基线建档 | {{PHASE_0_STATUS}} | {{PHASE_0_CONFIRMED}} | | | |
+| 1 | 需求分析与 PRD | {{PHASE_1_STATUS}} | {{PHASE_1_CONFIRMED}} | | | |
+| 2 | 交互设计 | {{PHASE_2_STATUS}} | {{PHASE_2_CONFIRMED}} | | | |
+| 3 | 架构设计 | {{PHASE_3_STATUS}} | {{PHASE_3_CONFIRMED}} | | | |
+| 4 | 并行开发 | {{PHASE_4_STATUS}} | - | | | |
+| 5 | 集成测试 | {{PHASE_5_STATUS}} | - | | | |
+
+**状态说明**：未开始 → 进行中 → 待确认 → 已完成 / 跳过
+
+---
+
+## 2. 团队分配
+
+### 角色分配
+
+| 角色 | Agent 名称 | 状态 | 负责阶段 |
+|------|-----------|------|----------|
+| 业务领域专家 | | | |
+| 产品经理 | | | |
+| 交互设计专家 | | | |
+| 后端架构师 | | | |
+| 后端开发工程师 | | | |
+| 前端开发工程师 | | | |
+| 集成测试专家 | | | |
+
+### Phase 4 模块开发进度
+
+| 模块 | 负责人 | 总任务数 | 已完成 | 进度 | 当前任务 |
+|------|--------|----------|--------|------|----------|
+| | | | | | |
+
+---
+
+## 3. 产出物清单
+
+### Phase 0: 基线建档
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| 现状 PRD | `docs/PRD.md` | |
+| 架构设计文档 | `docs/architecture.md` | |
+| 模块依赖关系 | `docs/module-dependencies.md` | |
+| 模块接口契约 | `src/<module>/docs/contracts.md` | |
+| 模块设计概览 | `src/<module>/docs/design-overview.md` | |
+
+### Phase 1: 需求分析
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| PRD | `docs/PRD.md` | |
+
+### Phase 2: 交互设计
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| 交互原型 | `docs/design/` | |
+
+### Phase 3: 架构设计
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| 架构文档 | `docs/architecture.md` | |
+| 模块契约 | `src/<module>/docs/contracts.md` | |
+| 依赖关系文档 | `docs/module-dependencies.md` | |
+
+### Phase 4: 并行开发
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| | | |
+
+### Phase 5: 集成测试
+
+| 产出物 | 文件路径 | 状态 |
+|--------|----------|------|
+| 集成测试报告 | | |
+
+**产出物状态**：未开始 / 进行中 / 待审核 / 已确认
+
+---
+
+## 4. 阻塞项与风险
+
+| 编号 | 类型 | 描述 | 影响阶段 | 负责人 | 状态 |
+|------|------|------|----------|--------|------|
+| | 阻塞/风险 | | | | 待解决/已解决 |
+
+---
+
+## 5. 下一步行动
+
+<!-- 本节是会话恢复的第一入口。保持 3-5 条最紧迫的待办事项。 -->
+
+1.
+2.
+3.

package/templates/module-dependencies.md.tpl

@@ -0,0 +1,71 @@
+# 模块间依赖关系文档
+
+> 所属服务：{{SERVICE_NAME}}（多服务项目填写；单服务项目删除此行）
+> 版本：v1.0
+> 最后更新：{{DATE}}
+
+---
+
+## 1. 模块清单
+
+| 模块名称 | 职责描述 | 负责人 |
+|----------|----------|--------|
+| | | |
+
+---
+
+## 2. 依赖关系总览
+
+<!-- 文本形式的依赖关系图 -->
+
+```
+模块A → 模块B     （同步调用：ServiceName.method）
+模块A → 模块C     （事件驱动：ModuleA.EventName）
+模块B → 模块D     （同步调用：ServiceName.method）
+```
+
+**依赖方向校验**：确认无循环依赖。
+
+---
+
+## 3. 同步调用依赖（Service 接口）
+
+| 调用方 | 被调用方 | 接口 | 用途 | 是否可选 |
+|--------|----------|------|------|----------|
+| | | `Service.method()` | | |
+
+---
+
+## 4. 事件驱动依赖（Domain Events）
+
+| 事件名称 | 发布方 | 订阅方 | 触发条件 | 处理说明 |
+|----------|--------|--------|----------|----------|
+| `Module.EventName` | | | | |
+
+---
+
+## 5. 前端接口依赖（Controller → 前端）
+
+| API 路径 | 所属模块 | 前端页面 | 描述 |
+|----------|----------|----------|------|
+| `METHOD /api/v1/...` | | | |
+
+---
+
+## 6. 跨服务依赖引用（仅多服务项目）
+
+<!-- 单服务项目删除本节。多服务项目在此记录本服务模块对其他服务的依赖。完整跨服务依赖详见 docs/service-dependencies.md。 -->
+
+| 目标服务 | 协议 | 接口路径/方法 | 调用方模块 | 用途 | 失败策略 |
+|----------|------|--------------|-----------|------|----------|
+| | HTTP/gRPC/MQ | | | | |
+
+---
+
+## 7. 依赖规则
+
+1. **禁止循环依赖**：如 A → B 则 B 不可 → A
+2. **新增依赖**：须更新本文档 + 双方模块的 `contracts.md`
+3. **删除依赖**：须更新本文档 + 通知原依赖方
+4. **契约变更**：须更新本文档 + 通知所有依赖方适配
+