cc-devflow 4.2.0 → 4.3.0

package/.claude/docs/templates/ARCHITECTURE_TEMPLATE.md

@@ -22,42 +22,34 @@
    → Read devflow/project.md (extract tech stack)
    → Check if devflow/ARCHITECTURE.md exists (update vs create mode)
 
-2. Load ARCHITECTURE_TEMPLATE.md
-   → Read template from .claude/docs/templates/ARCHITECTURE_TEMPLATE.md
-   → Prepare to fill all sections
-
-3. Analyze architecture type
+2. Analyze architecture type
    → Extract from project.md or infer from requirements
    → Architecture Type: Monolith | Microservices | Frontend-Backend | Serverless
    → Deployment Model: Desktop | Web | Mobile | CLI | Hybrid
-   → Fill header metadata
 
-4. Analyze tech stack
+3. Analyze tech stack
    → From project.md: extract Frontend, Backend, Database, Integration technologies
    → From TECH_DESIGN.md: extract additional libraries, frameworks
    → Organize by layer (Presentation, Business, Data, Integration)
 
-5. Generate Diagram 1: Feature Architecture (功能架构图)
+4. Generate Diagram 1: Feature Architecture (功能架构图)
    → From ROADMAP.md: extract all RM-IDs and REQ-IDs
    → Group related features into clusters (Core, Business, Support)
    → Identify dependencies from ROADMAP.md dependency graph
    → Generate Mermaid graph syntax
-   → Validate syntax (no missing brackets, valid node IDs)
 
-6. Generate Diagram 2: Technical Architecture (技术架构图)
+5. Generate Diagram 2: Technical Architecture (技术架构图)
    → Design layered architecture (Presentation → Business → Data → Integration)
    → Map technologies to layers from tech stack analysis
    → Show interactions between layers
    → Generate Mermaid graph syntax
-   → Validate syntax
 
-7. Generate Diagram 3: Module Structure (模块划分图)
+6. Generate Diagram 3: Module Structure (模块划分图)
    → Scan actual codebase structure (src/, .claude/, devflow/, etc.)
    → Identify key directories and their relationships
    → Generate Mermaid graph syntax
-   → Validate syntax
 
-8. Generate Diagram 4: Requirement Dependency (需求依赖图)
+7. Generate Diagram 4: Requirement Dependency (需求依赖图)
    → From ROADMAP.md: extract dependency relationships
    → Include both REQ-to-RM and RM-to-RM dependencies
    → Color-code by status:
@@ -65,30 +57,24 @@
       • In-progress REQs: #FFD700 (gold)
       • Planned RMs: #D3D3D3 (gray)
    → Generate Mermaid graph syntax
-   → Validate syntax
 
-9. Fill Architecture Decision Records (ADR)
+8. Fill Architecture Decision Records (ADR)
    → For each major architectural decision:
       • What: Decision made
       • Why: Rationale
       • When: Date
       • Impact: Consequences
    → Include decisions from TECH_DESIGN.md
-   → Format as structured sections
 
-10. Validate completeness
-    → All 4 diagrams generated
-    → All Mermaid syntax valid
-    → No {{PLACEHOLDER}} remaining
-    → Architecture reflects ROADMAP.md content
-    → If incomplete: ERROR "Complete missing sections"
+9. Validate completeness
+   → All 4 diagrams generated
+   → All Mermaid syntax valid
+   → No {{PLACEHOLDER}} remaining
+   → Architecture reflects ROADMAP.md content
 
-11. Write devflow/ARCHITECTURE.md
+10. Write devflow/ARCHITECTURE.md
     → Write complete file
     → Use UTF-8 encoding
-    → Ensure markdown formatting correct
-
-12. Return: SUCCESS (ARCHITECTURE.md generated)
 ```
 
 **重要**: 这是一个自执行模板。architecture-designer agent 应该按照 Execution Flow 生成完整的 ARCHITECTURE.md 文件。
@@ -98,407 +84,141 @@
 ## 架构类型
 
 - **应用类型**: {{ARCH_TYPE}}
-  - Monolith (单体应用)
-  - Microservices (微服务)
-  - Frontend-Backend Separation (前后端分离)
-  - Serverless (无服务器)
-
-- **部署方式**: {{DEPLOYMENT_MODEL}}
-  - Desktop Application (桌面应用 - Electron)
-  - Web Application (Web 应用)
-  - Mobile Application (移动应用)
-  - CLI Tool (命令行工具)
-  - Hybrid (混合模式)
+  - 选项: Monolith | Microservices | Frontend-Backend | Serverless | Hybrid
+- **部署模型**: {{DEPLOYMENT_MODEL}}
+  - 选项: Desktop | Web | Mobile | CLI | Hybrid
 
 ---
 
 ## 技术栈
 
-### Frontend
+### 前端层（Presentation Layer）
 {{FRONTEND_STACK}}
 
-_示例:_
-- **Framework**: React 18 + TypeScript
-- **State Management**: Redux Toolkit
-- **UI Library**: Ant Design
-- **Build Tool**: Vite
+_从 project.md 和 TECH_DESIGN.md 提取_
 
-### Backend
+### 业务层（Business Layer）
 {{BACKEND_STACK}}
 
-_示例:_
-- **Runtime**: Node.js 20
-- **Framework**: Express.js
-- **Language**: TypeScript
-- **API Style**: RESTful
+_从 project.md 和 TECH_DESIGN.md 提取_
 
-### Database
+### 数据层（Data Layer）
 {{DATABASE_STACK}}
 
-_示例:_
-- **Primary**: SQLite (embedded)
-- **Cache**: Redis (optional)
-- **Migration**: Knex.js
+_从 project.md 和 TECH_DESIGN.md 提取_
 
-### Integration
+### 集成层（Integration Layer）
 {{INTEGRATION_STACK}}
 
-_示例:_
-- **AI**: Claude API
-- **MCP**: Model Context Protocol Servers
-- **External APIs**: GitHub API, npm Registry
-
-### DevOps & Tools
-{{DEVOPS_STACK}}
-
-_示例:_
-- **Package Manager**: npm
-- **Testing**: Jest + React Testing Library
-- **Linting**: ESLint + Prettier
-- **Build**: Electron Builder
+_从 project.md 和 TECH_DESIGN.md 提取_
 
 ---
 
 ## 1. 功能架构图（Feature Architecture）
 
-### 核心模块划分
-
-本项目按照功能领域划分为三层架构：
-
-- **核心层 (Core)**: 提供基础认证、权限、安全等核心能力
-- **业务层 (Business)**: 实现具体业务功能，如会话管理、数据处理
-- **支撑层 (Support)**: 提供配置、日志、监控等支撑服务
-
-{{FEATURE_ARCHITECTURE_DESCRIPTION}}
-
-### 架构图
-
 ```mermaid
 graph TB
-    subgraph "核心层 Core"
-        {{CORE_MODULE_1}}[{{CORE_LABEL_1}}]
-        {{CORE_MODULE_2}}[{{CORE_LABEL_2}}]
+    subgraph Core["核心功能"]
+        {{CORE_FEATURES}}
     end
 
-    subgraph "业务层 Business"
-        {{BUSINESS_MODULE_1}}[{{BUSINESS_LABEL_1}}]
-        {{BUSINESS_MODULE_2}}[{{BUSINESS_LABEL_2}}]
-        {{BUSINESS_MODULE_3}}[{{BUSINESS_LABEL_3}}]
+    subgraph Business["业务功能"]
+        {{BUSINESS_FEATURES}}
     end
 
-    subgraph "支撑层 Support"
-        {{SUPPORT_MODULE_1}}[{{SUPPORT_LABEL_1}}]
-        {{SUPPORT_MODULE_2}}[{{SUPPORT_LABEL_2}}]
+    subgraph Support["支撑功能"]
+        {{SUPPORT_FEATURES}}
     end
 
-    {{BUSINESS_MODULE_1}} --> {{CORE_MODULE_1}}
-    {{BUSINESS_MODULE_2}} --> {{CORE_MODULE_2}}
-    {{BUSINESS_MODULE_3}} --> {{BUSINESS_MODULE_1}}
-    {{SUPPORT_MODULE_1}} --> {{CORE_MODULE_1}}
+    {{FEATURE_DEPENDENCIES}}
 ```
 
 _填充规则:_
-- Module ID 格式: 无空格无破折号（例如: `Auth`, `Session`, `Config`）
-- Label 格式: 中文简短描述（例如: `用户认证`, `会话管理`）
-- 箭头表示依赖关系：A → B 表示 A 依赖 B
-- 从 ROADMAP.md 提取模块名称和依赖关系
-
-_示例（完整图）:_
-```mermaid
-graph TB
-    subgraph "核心层 Core"
-        Auth[用户认证 REQ-001]
-        Perm[权限管理 REQ-002]
-        MultiAcc[多账号支持 RM-003]
-    end
-
-    subgraph "业务层 Business"
-        Session[会话管理 REQ-008]
-        Input[输入增强 RM-001]
-        Analysis[数据分析 RM-004]
-    end
-
-    subgraph "支撑层 Support"
-        Perf[性能优化 RM-002]
-        Config[配置管理]
-        Log[日志系统]
-    end
-
-    MultiAcc --> Perm
-    Session --> Auth
-    Input --> Session
-    Analysis --> Session
-    Perf --> Input
-    Config --> Auth
-    Log --> Session
-```
+- 从 ROADMAP.md 提取所有 RM-IDs 和 REQ-IDs
+- 按功能类型分组（核心/业务/支撑）
+- 标注依赖关系（箭头）
 
 ---
 
 ## 2. 技术架构图（Technical Architecture）
 
-### 分层设计
-
-本项目采用经典四层架构，确保关注点分离和可维护性：
-
-- **表现层 (Presentation)**: 用户界面和交互逻辑
-- **业务层 (Business)**: 核心业务逻辑和规则
-- **数据层 (Data)**: 数据持久化和访问
-- **集成层 (Integration)**: 外部系统集成
-
-{{TECHNICAL_ARCHITECTURE_DESCRIPTION}}
-
-### 架构图
-
 ```mermaid
 graph TB
-    subgraph "表现层 Presentation"
-        {{PRES_COMPONENT_1}}[{{PRES_LABEL_1}}]
-        {{PRES_COMPONENT_2}}[{{PRES_LABEL_2}}]
+    subgraph Presentation["表现层"]
+        {{PRESENTATION_COMPONENTS}}
     end
 
-    subgraph "业务层 Business"
-        {{BUS_COMPONENT_1}}[{{BUS_LABEL_1}}]
-        {{BUS_COMPONENT_2}}[{{BUS_LABEL_2}}]
+    subgraph Business["业务层"]
+        {{BUSINESS_COMPONENTS}}
     end
 
-    subgraph "数据层 Data"
-        {{DATA_COMPONENT_1}}[{{DATA_LABEL_1}}]
-        {{DATA_COMPONENT_2}}[{{DATA_LABEL_2}}]
+    subgraph Data["数据层"]
+        {{DATA_COMPONENTS}}
     end
 
-    subgraph "集成层 Integration"
-        {{INT_COMPONENT_1}}[{{INT_LABEL_1}}]
-        {{INT_COMPONENT_2}}[{{INT_LABEL_2}}]
+    subgraph Integration["集成层"]
+        {{INTEGRATION_COMPONENTS}}
     end
 
-    {{PRES_COMPONENT_1}} --> {{PRES_COMPONENT_2}}
-    {{PRES_COMPONENT_2}} --> {{BUS_COMPONENT_1}}
-    {{BUS_COMPONENT_1}} --> {{BUS_COMPONENT_2}}
-    {{BUS_COMPONENT_2}} --> {{DATA_COMPONENT_1}}
-    {{BUS_COMPONENT_2}} --> {{DATA_COMPONENT_2}}
-    {{BUS_COMPONENT_1}} --> {{INT_COMPONENT_1}}
-    {{BUS_COMPONENT_1}} --> {{INT_COMPONENT_2}}
+    {{LAYER_INTERACTIONS}}
 ```
 
 _填充规则:_
-- 从技术栈部分提取组件（React, Express, SQLite, Claude API, etc.）
-- Component ID: 技术简称无空格（例如: `UI`, `State`, `API`, `DB`）
-- Label: 技术全称（例如: `React + TypeScript`, `SQLite`）
-- 箭头表示调用关系或数据流向
-
-_示例（完整图）:_
-```mermaid
-graph TB
-    subgraph "表现层 Presentation"
-        UI[React + TypeScript]
-        State[Redux Toolkit]
-    end
-
-    subgraph "业务层 Business"
-        API[Express.js API]
-        BL[Business Logic]
-    end
-
-    subgraph "数据层 Data"
-        DB[(SQLite)]
-        Cache[(Redis)]
-    end
-
-    subgraph "集成层 Integration"
-        MCP[MCP Server]
-        Claude[Claude API]
-        GitHub[GitHub API]
-    end
-
-    UI --> State
-    State --> API
-    API --> BL
-    BL --> DB
-    BL --> Cache
-    API --> MCP
-    API --> Claude
-    BL --> GitHub
-```
+- 基于技术栈分析结果
+- 展示各层之间的交互关系
+- 标注关键技术选型
 
 ---
 
 ## 3. 模块划分图（Module Structure）
 
-### 代码组织
-
-本项目代码仓库按职责划分为以下主要模块：
-
-{{MODULE_STRUCTURE_DESCRIPTION}}
-
-### 架构图
-
 ```mermaid
-graph LR
-    subgraph "{{PROJECT_NAME}}"
-        subgraph "{{DIR_GROUP_1}}"
-            {{DIR_1_1}}[{{DIR_LABEL_1_1}}]
-            {{DIR_1_2}}[{{DIR_LABEL_1_2}}]
-            {{DIR_1_3}}[{{DIR_LABEL_1_3}}]
-        end
-
-        subgraph "{{DIR_GROUP_2}}"
-            {{DIR_2_1}}[{{DIR_LABEL_2_1}}]
-            {{DIR_2_2}}[{{DIR_LABEL_2_2}}]
-            {{DIR_2_3}}[{{DIR_LABEL_2_3}}]
-        end
-
-        subgraph "{{DIR_GROUP_3}}"
-            {{DIR_3_1}}[{{DIR_LABEL_3_1}}]
-            {{DIR_3_2}}[{{DIR_LABEL_3_2}}]
-        end
+graph TB
+    subgraph Root["项目根目录"]
+        {{ROOT_MODULES}}
     end
 
-    {{DIR_2_2}} --> {{DIR_2_1}}
-    {{DIR_2_1}} --> {{DIR_2_3}}
+    {{MODULE_RELATIONSHIPS}}
 ```
 
 _填充规则:_
-- 扫描实际目录结构: src/, .claude/, devflow/, etc.
-- Dir Group: 主要目录（例如: "src/", ".claude/"）
-- Dir Label: 子目录名称（例如: "components/", "services/"）
-- 箭头表示依赖关系（可选）
-
-_示例（完整图）:_
-```mermaid
-graph LR
-    subgraph "anna-agent"
-        subgraph "src/"
-            Comp[components/]
-            Serv[services/]
-            Utils[utils/]
-            Types[types/]
-        end
-
-        subgraph ".claude/"
-            Agents[agents/]
-            Cmds[commands/]
-            Scripts[scripts/]
-            Docs[docs/]
-        end
-
-        subgraph "devflow/"
-            Reqs[requirements/]
-            Roadmap[ROADMAP.md]
-            Arch[ARCHITECTURE.md]
-        end
-    end
-
-    Cmds --> Agents
-    Cmds --> Scripts
-    Agents --> Docs
-    Comp --> Serv
-    Serv --> Utils
-```
+- 扫描实际代码库结构
+- 识别关键目录及其职责
+- 展示模块间依赖关系
 
 ---
 
 ## 4. 需求依赖图（Requirement Dependency）
 
-### 依赖关系
-
-需求间依赖关系展示了功能演进的顺序和关系：
-
-{{REQUIREMENT_DEPENDENCY_DESCRIPTION}}
+```mermaid
+graph LR
+    {{REQUIREMENT_NODES}}
+    {{REQUIREMENT_DEPENDENCIES}}
 
-### 架构图
+    classDef completed fill:#90EE90
+    classDef inProgress fill:#FFD700
+    classDef planned fill:#D3D3D3
 
-```mermaid
-graph TD
-    {{REQ_NODE_1}}[{{REQ_LABEL_1}}] --> {{REQ_NODE_2}}[{{REQ_LABEL_2}}]
-    {{REQ_NODE_2}} --> {{RM_NODE_1}}[{{RM_LABEL_1}}]
-    {{REQ_NODE_3}}[{{REQ_LABEL_3}}] --> {{RM_NODE_2}}[{{RM_LABEL_2}}]
-
-    style {{REQ_NODE_1}} fill:#90EE90
-    style {{REQ_NODE_2}} fill:#90EE90
-    style {{REQ_NODE_3}} fill:#FFD700
-    style {{RM_NODE_1}} fill:#D3D3D3
-    style {{RM_NODE_2}} fill:#D3D3D3
+    {{REQUIREMENT_CLASSES}}
 ```
 
 _填充规则:_
-- 从 ROADMAP.md 的 Dependency Graph 提取依赖关系
-- Node ID: 去除破折号（REQ001, REQ010, RM001）
-- Node Label: 带破折号和标题（`REQ-001: 用户认证`）
-- 颜色编码:
-  - #90EE90 (浅绿): 已完成的 REQ
-  - #FFD700 (金色): 进行中的 REQ
-  - #D3D3D3 (浅灰): 计划中的 RM
-- 箭头方向: 依赖项 → 被依赖项
-
-_示例（完整图）:_
-```mermaid
-graph TD
-    REQ001[REQ-001: 用户认证] --> REQ002[REQ-002: 权限管理]
-    REQ008[REQ-008: 会话管理] --> REQ001
-    REQ009[REQ-009: 输入增强] --> REQ008
-
-    REQ002 --> RM003[RM-003: 多账号支持]
-    REQ009 --> RM001[RM-001: 输入框 v2.0]
-    REQ010[REQ-010: 数据分析] --> RM004[RM-004: 数据分析增强]
-
-    style REQ001 fill:#90EE90
-    style REQ002 fill:#90EE90
-    style REQ008 fill:#90EE90
-    style REQ009 fill:#90EE90
-    style REQ010 fill:#FFD700
-    style RM001 fill:#D3D3D3
-    style RM003 fill:#D3D3D3
-    style RM004 fill:#D3D3D3
-```
+- 从 ROADMAP.md 提取依赖关系
+- 按状态着色（完成/进行中/计划中）
+- 展示 REQ-to-RM 和 RM-to-RM 依赖
 
 ---
 
 ## 架构决策记录（Architecture Decision Records）
 
-### ADR-{{ADR_NUMBER}}: {{DECISION_TITLE}}
-
-- **日期**: {{ADR_DATE}} 北京时间
-- **状态**: {{ADR_STATUS}} (Proposed | Accepted | Deprecated | Superseded)
-- **决策者**: {{DECISION_MAKER}}
-
-**背景 (Context)**:
-{{ADR_CONTEXT}}
-
-**决策 (Decision)**:
-{{ADR_DECISION}}
-
-**理由 (Rationale)**:
-{{ADR_RATIONALE}}
-
-**影响 (Consequences)**:
-- **正面影响**:
-  - {{POSITIVE_CONSEQUENCE_1}}
-  - {{POSITIVE_CONSEQUENCE_2}}
-
-- **负面影响**:
-  - {{NEGATIVE_CONSEQUENCE_1}}
-  - {{NEGATIVE_CONSEQUENCE_2}}
-
-- **中性影响**:
-  - {{NEUTRAL_CONSEQUENCE_1}}
-
-**替代方案 (Alternatives Considered)**:
-1. {{ALTERNATIVE_1}}
-   - 优势: {{ALT_1_PROS}}
-   - 劣势: {{ALT_1_CONS}}
-   - 为何未选择: {{ALT_1_REASON}}
-
----
-
-_填充规则:_
-- ADR Number: 序号 001, 002, 003...
-- 从 TECH_DESIGN.md 提取架构决策
-- Status: 标记决策的当前状态
-- Context: 说明为什么需要做这个决策（问题或需求）
-- Decision: 明确说明做了什么决策
-- Rationale: 为什么选择这个决策（技术、业务、团队等因素）
-- Consequences: 这个决策带来的影响（好的、坏的、中性的）
+### ADR 格式
+每个 ADR 包含:
+- Date: 决策日期
+- Status: Accepted | Proposed | Deprecated
+- Context: 背景和问题
+- Decision: 决策内容
+- Rationale: 为什么选择这个决策
+- Consequences: 这个决策带来的影响
 - Alternatives: 考虑过但未选择的其他方案
 
 _示例:_
@@ -517,7 +237,6 @@ _示例:_
 - 团队熟悉 Web 技术栈（React + TypeScript）
 - Electron 拥有成熟的生态系统和社区支持
 - 可复用 Web 开发经验和组件库
-- VS Code、Slack 等成功案例证明其可行性
 
 **影响**:
 - **正面影响**:
@@ -530,9 +249,6 @@ _示例:_
   - 应用包体积较大（100MB+）
   - 启动速度相对原生应用较慢
 
-- **中性影响**:
-  - 需要额外关注性能优化
-
 **替代方案**:
 1. **Tauri (Rust + Web)**
    - 优势: 更小的包体积、更低的内存占用
@@ -549,13 +265,11 @@ _示例:_
 ## 架构演进路径
 
 ### 当前状态（As-Is）
-
 {{CURRENT_STATE}}
 
 _描述当前架构的状态、已实现的功能模块、技术债务等_
 
 ### 目标状态（To-Be）
-
 {{TARGET_STATE}}
 
 _根据 ROADMAP.md 描述未来 3 个月的目标架构状态_
@@ -586,48 +300,33 @@ _填充规则:_
 | API 响应时间 | {{CURRENT_API_LATENCY}} | {{TARGET_API_LATENCY}} | {{API_TIMELINE}} |
 
 ### 可扩展性要求
-
 {{SCALABILITY_REQUIREMENTS}}
 
 _描述如何支持用户增长、数据增长、功能扩展_
 
 ### 安全要求
-
 {{SECURITY_REQUIREMENTS}}
 
 _描述认证、授权、加密、审计等安全机制_
 
-### 可维护性要求
-
-{{MAINTAINABILITY_REQUIREMENTS}}
-
-_描述代码质量、测试覆盖率、文档完整性等要求_
-
 ---
 
 ## Validation Checklist
 
-验证此架构文档是否完整：
-
-- [ ] 所有 4 种架构图已生成
-- [ ] 所有 Mermaid 代码语法正确
-- [ ] 架构图反映 ROADMAP.md 内容
-- [ ] 技术栈与 project.md 一致
-- [ ] 至少有 1 条 ADR 记录
-- [ ] 架构演进路径清晰
-- [ ] NFRs 已定义
+在输出 ARCHITECTURE.md 前，确保:
 
-**Ready for Team Review**: {{READY_STATUS}}
-
-_填充规则:_
-- 每个 checkbox 应被标记为 `[x]` 或 `[ ]`
-- Ready Status: YES | NO (with reasons)
+- [x] 所有 4 个 Mermaid 图表已生成
+- [x] 所有 Mermaid 语法有效（无语法错误）
+- [x] 所有 {{PLACEHOLDER}} 已填充
+- [x] 架构反映了 ROADMAP.md 的内容
+- [x] 至少有 1 个 ADR 记录
+- [x] 技术栈信息完整
+- [x] 演进路径清晰
 
 ---
 
-**生成说明**:
-1. 所有 `{{PLACEHOLDER}}` 必须被实际内容替换
-2. 所有 Mermaid 代码必须语法正确且能渲染
-3. 架构图应基于 ROADMAP.md 和实际代码结构生成
-4. ADR 应从 TECH_DESIGN.md 提取或新创建
-5. 所有日期使用北京时间 + ISO 8601 格式
+**Template Version**: 2.0.0 (Slimmed from 633 lines to ~350 lines, -45%)
+**Last Updated**: 2026-03-12
+**Maintainer**: CC-DevFlow Team
+
+**[PROTOCOL]**: 变更时更新此头部，然后检查 CLAUDE.md