Merge pull request #10 from catlog22/claude/audit-command-docs-agents-011tVdT2942cX3W3fib9pYQz

Claude/audit command docs agents 011t vd t2942c x3 w3fib9p y qz
2026-02-05 01:50:27 +08:00 · 2025-11-20 11:05:05 +08:00
parent 292dc113e3 c56bf68d87
commit 957473aa71
2 changed files with 278 additions and 104 deletions
--- a/.claude/commands/workflow/tdd-plan.md
+++ b/.claude/commands/workflow/tdd-plan.md
@@ -417,110 +417,6 @@ Convert user input to TDD-structured format:
 - **Command failure**: Keep phase in_progress, report error
 - **TDD validation failure**: Report incomplete chains or wrong dependencies

-## TDD Workflow Enhancements
-
-### Overview
-The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
-
-### Key Improvements
-
-#### 1. Test Coverage Analysis (Phase 3)
-**Adopted from test-gen workflow**
-
-Before planning TDD tasks, the workflow now analyzes the existing codebase:
- Detects existing test patterns and conventions
- Identifies current test coverage
- Discovers related components and integration points
- Detects test framework automatically
-
-**Benefits**:
- Context-aware TDD planning
- Avoids duplicate test creation
- Enables integration with existing tests
- No longer assumes greenfield scenarios
-
-#### 2. Iterative Green Phase with Test-Fix Cycle
-**Adopted from test-gen workflow**
-
-IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
-
-**Enhanced IMPL Task Flow**:
-```
-1. Write minimal implementation code
-2. Execute test suite
-3. IF tests pass → Complete task
-4. IF tests fail → Enter fix cycle:
-   a. Gemini diagnoses with bug-fix template
-   b. Apply fix (manual or Codex)
-   c. Retest
-   d. Repeat (max 3 iterations)
-5. IF max iterations → Auto-revert changes 🔄
-```
-
-**Benefits**:
- Faster feedback within Green phase
- Autonomous recovery from implementation errors
- Systematic debugging with Gemini
- Safe rollback prevents broken state
-
-#### 3. Agent-Driven Planning
-**From plan --agent workflow**
-
-Supports action-planning-agent for more autonomous TDD planning with:
- MCP tool integration (code-index, exa)
- Memory-first principles
- Brainstorming artifact integration
- Task merging over decomposition
-
-### Workflow Comparison
-
-| Aspect | Previous | Current (Optimized) |
-|--------|----------|---------------------|
-| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
-| **Context** | Greenfield assumption | Existing codebase aware |
-| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
-| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
-| **Green Phase** | Single implementation | Iterative with fix cycle |
-| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
-| **Test Analysis** | None | Deep coverage analysis |
-| **Feedback Loop** | Post-execution | During Green phase |
-| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
-| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
-
-### Migration Notes
-
-**Backward Compatibility**: Fully compatible
- Existing TDD workflows continue to work
- New features are additive, not breaking
- Phase 3 can be skipped if test-context-gather not available
-
-**Session Structure**:
-```
-.workflow/active/WFS-xxx/
-├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
-├── TODO_LIST.md (with internal TDD phase indicators)
-├── .process/
-│   ├── context-package.json
-│   ├── test-context-package.json
-│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
-└── .task/
-    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
-    ├── IMPL-2.json (Complete TDD task)
-    ├── IMPL-3.json (Complex feature container, if needed)
-    ├── IMPL-3.1.json (Complex feature subtask, if needed)
-    └── IMPL-3.2.json (Complex feature subtask, if needed)
-```
-
-**File Count Comparison**:
- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
- **New structure**: 5 features = 5 task files (IMPL-N × 5)
- **Complex features**: Add container + subtasks only when necessary
-
-**Configuration Options** (in IMPL tasks):
- `meta.max_iterations`: Fix attempts (default: 3)
- `meta.use_codex`: Auto-fix mode (default: false)
-
 ## Related Commands

 **Prerequisite Commands**:
--- a/COMMAND_DOCS_AUDIT_REPORT.md
+++ b/COMMAND_DOCS_AUDIT_REPORT.md
@@ -0,0 +1,278 @@
+# 命令文档审计报告
+
+**审计日期**: 2025-11-20
+**审计范围**: 73个命令文档文件
+**审计方法**: 自动化扫描 + 手动内容分析
+
+---
+
+## 发现的问题
+
+### 1. 包含版本信息的文件
+
+#### [CRITICAL] version.md
+**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/version.md`
+
+**问题位置**:
+- 第1-3行：包含在YAML头中
+- 第96-102行：示例中包含完整版本号和发布日期（如"v3.2.2"、"2025-10-03"）
+- 第127-130行：包含开发版本号和日期
+- 第155-172行：版本比较和升级建议
+
+**内容摘要**:
+```
+Latest Stable: v3.2.2
+Release: v3.2.2: Independent Test-Gen Workflow with Cross-Session Context
+Published: 2025-10-03T04:10:08Z
+
+Latest Dev: a03415b
+Message: feat: Add version tracking and upgrade check system
+Date: 2025-10-03T04:46:44Z
+```
+
+**严重程度**: ⚠️ 高 - 文件本质上是版本管理命令，但包含具体版本号、发布日期和完整版本历史
+
+---
+
+### 2. 包含额外无关内容的文件
+
+#### [HIGH] tdd-plan.md
+**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/workflow/tdd-plan.md`
+
+**问题位置**: 第420-523行
+
+**部分内容**:
+```markdown
+## TDD Workflow Enhancements
+
+### Overview
+The TDD workflow has been significantly enhanced by integrating best practices
+from both traditional `plan --agent` and `test-gen` workflows...
+
+### Key Improvements
+
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow**
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow**
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow**
+
+### Workflow Comparison
+| Aspect | Previous | Current (Optimized) |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
+| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
+
+### Migration Notes
+**Backward Compatibility**: Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+```
+
+**问题分析**:
+- 包含"增强"、"改进"、"演进"等版本历史相关内容
+- 包含"工作流比较"部分，对比了"之前"和"现在"的版本
+- 包含"迁移说明"，描述了从旧版本的升级路径
+- 约100行内容（第420-523行）不是关于命令如何使用，而是关于如何改进的
+
+**严重程度**: ⚠️ 中-高 - 约18%的文件内容（100/543行）是版本演进相关，而不是核心功能说明
+
+---
+
+### 3. 任务不够专注的文件
+
+#### [MEDIUM] tdd-plan.md (继续)
+**问题**: 文件中包含过多关于与其他命令（plan、test-gen）集成的说明
+
+**相关部分**:
+- 第475-488行：与"plan --agent"工作流的比较
+- 第427-441行：描述从test-gen工作流"采纳"的特性
+- 第466-473行：描述从plan --agent工作流"采纳"的特性
+
+**问题分析**: 虽然这些集成说明可能有用，但在命令文档中过度强调其他命令的关系，使文档的焦点分散。建议这类内容应放在项目级文档或架构文档中，而不是在具体命令文档中。
+
+**严重程度**: ⚠️ 中 - 降低了文档的焦点，但不是严重问题
+
+---
+
+## 合规文件统计
+
+### 审计结果汇总
+
+| 类别 | 计数 | 百分比 |
+|------|------|--------|
+| **完全合规的文件** | 70 | 95.9% |
+| **有版本信息的文件** | 1 | 1.4% |
+| **包含额外无关内容的文件** | 1 | 1.4% |
+| **任务不够专注的文件** | 1* | 1.4% |
+| **总计** | 73 | 100% |
+
+*注: tdd-plan.md 同时出现在"额外无关内容"和"任务不专注"两个类别中
+
+### 问题严重程度分布
+
+| 严重程度 | 文件数 | 说明 |
+|---------|--------|------|
+| CRITICAL | 0 | 没有需要立即阻止执行的问题 |
+| HIGH | 1 | version.md - 包含完整版本号和发布信息 |
+| MEDIUM | 1 | tdd-plan.md - 包含过度的版本演进说明和工作流对比 |
+| LOW | 0 | 无其他问题 |
+
+---
+
+## 详细发现
+
+### version.md - 完整分析
+
+**问题本质**: version.md命令的存在目的就是管理和报告版本信息。文件中包含版本号、发布日期、更新日志等内容不仅是合理的，而是必需的。
+
+**但审计角度**: 根据用户的审计标准：
+- ✓ "包含版本号、版本历史、changelog等内容" - **是的，明确包含**
+  - 示例版本号: v3.2.1, v3.2.2, 3.4.0-dev
+  - 发布日期: 2025-10-03T12:00:00Z
+  - 版本历史信息和升级路径
+
+**结论**: 该文件符合审计标准中的"版本信息"类别，应被标记为有问题（尽管这是功能需求）
+
+---
+
+### tdd-plan.md - 完整分析
+
+**第一个问题 - 额外的版本演进信息**:
+```
+## TDD Workflow Enhancements (行420)
+### Overview
+The TDD workflow has been **significantly enhanced** by integrating best practices
+from **both traditional `plan --agent` and `test-gen` workflows**
+
+### Key Improvements
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow** (行428)
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow** (行443)
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow** (行467)
+```
+
+这部分内容完全是关于命令的历史演变和改进，不是关于如何使用该命令。
+
+**第二个问题 - 工作流对比表**:
+```
+### Workflow Comparison (行475)
+| Aspect | Previous | Current (Optimized) |
+| **Phases** | 6 | 7 |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
+```
+
+直接对比了"之前"和"现在"的实现，这是版本历史相关内容。
+
+**第三个问题 - 迁移说明**:
+```
+### Migration Notes (行490)
+**Backward Compatibility**: Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+```
+
+这是版本升级路径说明，不是命令核心功能文档的一部分。
+
+**统计**:
+- 总行数: 543行
+- 有问题的行: ~103行（第420-523行）
+- 占比: ~19%
+
+**结论**: tdd-plan.md 同时违反了两个审计标准：
+1. 包含版本演进历史相关内容
+2. 过度描述与其他命令的关系（缺乏任务专注度）
+
+---
+
+## 建议
+
+### 高优先级
+
+1. **移除 version.md 中的具体版本号**
+   - 当前做法: 包含硬编码的版本号、日期等
+   - 建议: 使用变量或运行时获取版本信息，文档中只描述版本命令的功能
+   - 理由: 版本号应该由版本控制系统管理，而不是在文档中硬编码
+
+2. **从 tdd-plan.md 中移除第420-523行（版本演进部分）**
+   - 当前: ~103行关于"增强"、"改进"、"迁移"的内容
+   - 建议: 移到单独的"CHANGELOG.md"或项目级文档
+   - 理由: 这是历史演变信息，不是使用指南
+
+### 中优先级
+
+3. **重构 tdd-plan.md 中的工作流关系**
+   - 当前: 第475-495行详细对比与其他命令的区别
+   - 建议: 简化对其他命令的引用，保留"Related Commands"部分即可
+   - 理由: 过度关注与其他命令的关系分散了文档焦点
+
+4. **统一版本信息管理策略**
+   - 建议: 建立项目级文档规范，明确哪些信息应在命令文档中出现
+   - 范围: 适用于所有命令文档
+
+---
+
+## 合规性评定
+
+### 总体评分: 96/100
+
+- ✓ **整体质量高**: 95.9%的文件完全合规
+- ⚠️ **两个文件需要整改**:
+  - version.md: 版本信息管理需要优化
+  - tdd-plan.md: 版本演进内容需要分离
+
+### 推荐行动
+
+| 优先级 | 行动 | 预期影响 |
+|--------|------|---------|
+| **高** | 清理 version.md 的硬编码版本号 | 提高版本管理的可维护性 |
+| **高** | 从 tdd-plan.md 移除第420-523行 | 提高文档专注度，减少19% |
+| **中** | 建立版本信息管理规范 | 防止未来重复问题 |
+| **低** | 简化 tdd-plan.md 中的工作流关系说明 | 进一步改善文档清晰度 |
+
+---
+
+## 附录
+
+### 审计方法论
+
+1. **自动扫描**: 使用grep搜索关键词（version, changelog, release, history等）
+2. **内容分析**: 手动读取匹配文件的完整内容
+3. **结构分析**: 检查是否包含与核心功能无关的内容
+4. **统计分析**: 计算问题内容占比
+
+### 数据来源
+
+- 总文件数: 73
+- 详细分析文件: 15
+- 快速扫描文件: 58
+
+### 文件列表（完整性检查）
+
+已审计的所有命令文档:
+- ✓ version.md (有问题)
+- ✓ enhance-prompt.md
+- ✓ test-fix-gen.md
+- ✓ test-gen.md
+- ✓ test-cycle-execute.md
+- ✓ tdd-plan.md (有问题)
+- ✓ tdd-verify.md
+- ✓ status.md
+- ✓ review.md
+- ✓ plan.md
+- ✓ lite-plan.md
+- ✓ lite-execute.md
+- ✓ init.md
+- ✓ execute.md
+- ✓ action-plan-verify.md
+- ... 以及其他58个文件 (全部合规)
+
+---
+
+**审计完成** - 生成时间: 2025-11-20