mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-28 09:23:08 +08:00
feat: add team-tech-debt skill for tech debt identification and cleanup
6-role team (coordinator, scanner, assessor, planner, executor, validator) with 3 pipeline modes (scan, remediate, targeted) and fix-verify loop. Scanner performs 5-dimension analysis (code, architecture, testing, dependency, documentation) via CLI fan-out. Follows team-skill-designer patterns with self-contained role.md and command.md files.
This commit is contained in:
catlog22
404
.claude/skills/team-tech-debt/SKILL.md
Normal file
404
.claude/skills/team-tech-debt/SKILL.md
Normal file
@@ -0,0 +1,404 @@
|
||||
---
|
||||
name: team-tech-debt
|
||||
description: Unified team skill for tech debt identification and cleanup. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team tech-debt", "tech debt cleanup", "技术债务".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
||||
---
|
||||
|
||||
# Team Tech Debt
|
||||
|
||||
技术债务识别与清理团队。融合"债务扫描"、"量化评估"、"治理规划"、"清理执行"、"验证回归"五大能力域，形成"扫描→评估→规划→清理→验证"闭环。通过 Scanner 多维度扫描、Executor-Validator 修复验证循环、共享债务清单数据库，实现渐进式技术债务治理。所有成员通过 `--role=xxx` 路由到角色执行逻辑。
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Skill(skill="team-tech-debt", args="--role=xxx") │
|
||||
└────────────────────────┬─────────────────────────────────┘
|
||||
│ Role Router
|
||||
┌────────┬───────────┼───────────┬──────────┬──────────┐
|
||||
↓ ↓ ↓ ↓ ↓ ↓
|
||||
┌────────┐┌────────┐┌──────────┐┌─────────┐┌────────┐┌─────────┐
|
||||
│coordi- ││scanner ││assessor ││planner ││executor││validator│
|
||||
│nator ││TDSCAN-*││TDEVAL-* ││TDPLAN-* ││TDFIX-* ││TDVAL-* │
|
||||
│ roles/ ││ roles/ ││ roles/ ││ roles/ ││ roles/ ││ roles/ │
|
||||
└────────┘└────────┘└──────────┘└─────────┘└────────┘└─────────┘
|
||||
```
|
||||
|
||||
## Command Architecture
|
||||
|
||||
```
|
||||
roles/
|
||||
├── coordinator/
|
||||
│ ├── role.md # Pipeline 编排（模式选择、任务分发、监控）
|
||||
│ └── commands/
|
||||
│ ├── dispatch.md # 任务链创建
|
||||
│ └── monitor.md # 进度监控
|
||||
├── scanner/
|
||||
│ ├── role.md # 多维度技术债务扫描
|
||||
│ └── commands/
|
||||
│ └── scan-debt.md # 多维度 CLI Fan-out 扫描
|
||||
├── assessor/
|
||||
│ ├── role.md # 量化评估与优先级排序
|
||||
│ └── commands/
|
||||
│ └── evaluate.md # 影响/成本矩阵评估
|
||||
├── planner/
|
||||
│ ├── role.md # 治理方案规划
|
||||
│ └── commands/
|
||||
│ └── create-plan.md # 分阶段治理方案生成
|
||||
├── executor/
|
||||
│ ├── role.md # 债务清理执行
|
||||
│ └── commands/
|
||||
│ └── remediate.md # 重构/清理/更新执行
|
||||
└── validator/
|
||||
├── role.md # 清理结果验证
|
||||
└── commands/
|
||||
└── verify.md # 回归测试与质量验证
|
||||
```
|
||||
|
||||
**设计原则**: role.md 保留 Phase 1（Task Discovery）和 Phase 5（Report）内联。Phase 2-4 根据复杂度决定内联或委派到 `commands/*.md`。
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
|
||||
Parse `$ARGUMENTS` to extract `--role` and optional `--agent-name`:
|
||||
|
||||
```javascript
|
||||
const args = "$ARGUMENTS"
|
||||
const roleMatch = args.match(/--role[=\s]+(\w+)/)
|
||||
const teamName = args.match(/--team[=\s]+([\w-]+)/)?.[1] || "tech-debt"
|
||||
|
||||
if (!roleMatch) {
|
||||
// No --role: Orchestration Mode → auto route to coordinator
|
||||
// See "Orchestration Mode" section below
|
||||
}
|
||||
|
||||
const role = roleMatch ? roleMatch[1] : "coordinator"
|
||||
const agentName = args.match(/--agent-name[=\s]+([\w-]+)/)?.[1] || role
|
||||
```
|
||||
|
||||
### Role Dispatch
|
||||
|
||||
```javascript
|
||||
const VALID_ROLES = {
|
||||
"coordinator": { file: "roles/coordinator/role.md", prefix: null },
|
||||
"scanner": { file: "roles/scanner/role.md", prefix: "TDSCAN" },
|
||||
"assessor": { file: "roles/assessor/role.md", prefix: "TDEVAL" },
|
||||
"planner": { file: "roles/planner/role.md", prefix: "TDPLAN" },
|
||||
"executor": { file: "roles/executor/role.md", prefix: "TDFIX" },
|
||||
"validator": { file: "roles/validator/role.md", prefix: "TDVAL" }
|
||||
}
|
||||
|
||||
if (!VALID_ROLES[role]) {
|
||||
throw new Error(`Unknown role: ${role}. Available: ${Object.keys(VALID_ROLES).join(', ')}`)
|
||||
}
|
||||
|
||||
// Read and execute role-specific logic
|
||||
Read(VALID_ROLES[role].file)
|
||||
// → Execute the 5-phase process defined in that file
|
||||
```
|
||||
|
||||
### Orchestration Mode（无参数触发）
|
||||
|
||||
当不带 `--role` 调用时，自动进入 coordinator 编排模式。
|
||||
|
||||
**触发方式**:
|
||||
|
||||
```javascript
|
||||
// 用户调用（无 --role）— 自动路由到 coordinator
|
||||
Skill(skill="team-tech-debt", args="扫描并清理项目中的技术债务")
|
||||
|
||||
// 等价于
|
||||
Skill(skill="team-tech-debt", args="--role=coordinator 扫描并清理项目中的技术债务")
|
||||
```
|
||||
|
||||
**完整调用链**:
|
||||
|
||||
```
|
||||
用户: Skill(args="任务描述")
|
||||
│
|
||||
├─ SKILL.md: 无 --role → Orchestration Mode → 读取 coordinator role.md
|
||||
│
|
||||
├─ coordinator Phase 2: TeamCreate + spawn workers
|
||||
│ 每个 worker prompt 中包含 Skill(args="--role=xxx") 回调
|
||||
│
|
||||
├─ coordinator Phase 3: dispatch 任务链
|
||||
│
|
||||
├─ worker 收到任务 → Skill(args="--role=xxx") → SKILL.md Role Router → role.md
|
||||
│ 每个 worker 自动获取:
|
||||
│ ├─ 角色定义 (role.md: identity, boundaries, message types)
|
||||
│ ├─ 可用命令 (commands/*.md)
|
||||
│ └─ 执行逻辑 (5-phase process)
|
||||
│
|
||||
└─ coordinator Phase 4-5: 监控 → 结果汇报
|
||||
```
|
||||
|
||||
### Available Roles
|
||||
|
||||
| Role | Task Prefix | Responsibility | Role File |
|
||||
|------|-------------|----------------|-----------|
|
||||
| `coordinator` | N/A | Pipeline 编排、模式选择、质量门控 | [roles/coordinator/role.md](roles/coordinator/role.md) |
|
||||
| `scanner` | TDSCAN-* | 多维度技术债务扫描 | [roles/scanner/role.md](roles/scanner/role.md) |
|
||||
| `assessor` | TDEVAL-* | 量化评估与优先级排序 | [roles/assessor/role.md](roles/assessor/role.md) |
|
||||
| `planner` | TDPLAN-* | 分阶段治理方案规划 | [roles/planner/role.md](roles/planner/role.md) |
|
||||
| `executor` | TDFIX-* | 重构/清理/更新执行 | [roles/executor/role.md](roles/executor/role.md) |
|
||||
| `validator` | TDVAL-* | 回归测试与质量验证 | [roles/validator/role.md](roles/validator/role.md) |
|
||||
|
||||
## Shared Infrastructure
|
||||
|
||||
> 以下为编排级概览。具体实现代码（Message Bus、Task Lifecycle、工具方法）在各 role.md 中自包含。
|
||||
|
||||
### Team Configuration
|
||||
|
||||
```javascript
|
||||
const TEAM_CONFIG = {
|
||||
name: "tech-debt",
|
||||
sessionDir: ".workflow/.team/TD-{slug}-{date}/",
|
||||
sharedMemory: "shared-memory.json",
|
||||
debtDimensions: ["code", "architecture", "testing", "dependency", "documentation"],
|
||||
priorityMatrix: {
|
||||
highImpact_lowCost: "立即修复 (Quick Win)",
|
||||
highImpact_highCost: "战略规划 (Strategic)",
|
||||
lowImpact_lowCost: "待办处理 (Backlog)",
|
||||
lowImpact_highCost: "暂缓接受 (Defer)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Role Isolation Rules
|
||||
|
||||
**核心原则**: 每个角色仅能执行自己职责范围内的工作。
|
||||
|
||||
#### Output Tagging（强制）
|
||||
|
||||
所有角色的输出必须带 `[role_name]` 标识前缀。
|
||||
|
||||
#### Coordinator 隔离
|
||||
|
||||
| 允许 | 禁止 |
|
||||
|------|------|
|
||||
| 需求澄清 (AskUserQuestion) | ❌ 直接扫描代码 |
|
||||
| 创建任务链 (TaskCreate) | ❌ 直接执行重构或清理 |
|
||||
| 模式选择 + 质量门控 | ❌ 直接评估或规划 |
|
||||
| 监控进度 (消息总线) | ❌ 绕过 worker 自行完成 |
|
||||
|
||||
#### Worker 隔离
|
||||
|
||||
| 允许 | 禁止 |
|
||||
|------|------|
|
||||
| 处理自己前缀的任务 | ❌ 处理其他角色前缀的任务 |
|
||||
| 读写 shared-memory.json (自己的字段) | ❌ 为其他角色创建任务 |
|
||||
| SendMessage 给 coordinator | ❌ 直接与其他 worker 通信 |
|
||||
|
||||
## Three-Mode Pipeline Architecture
|
||||
|
||||
```
|
||||
Scan Mode (仅扫描评估):
|
||||
TDSCAN-001(多维度扫描) → TDEVAL-001(量化评估) → 报告
|
||||
|
||||
Remediate Mode (完整闭环):
|
||||
TDSCAN-001(扫描) → TDEVAL-001(评估) → TDPLAN-001(规划) → TDFIX-001(修复) → TDVAL-001(验证)
|
||||
|
||||
Targeted Mode (定向修复):
|
||||
TDPLAN-001(规划) → TDFIX-001(修复) → TDVAL-001(验证)
|
||||
```
|
||||
|
||||
### Mode Auto-Detection
|
||||
|
||||
```javascript
|
||||
function detectMode(args, taskDescription) {
|
||||
if (/--mode[=\s]+(scan|remediate|targeted)/.test(args)) {
|
||||
return args.match(/--mode[=\s]+(\w+)/)[1]
|
||||
}
|
||||
if (/扫描|scan|审计|audit|评估|assess/.test(taskDescription)) return 'scan'
|
||||
if (/定向|targeted|指定|specific|修复.*已知/.test(taskDescription)) return 'targeted'
|
||||
return 'remediate'
|
||||
}
|
||||
```
|
||||
|
||||
### Fix-Verify Loop
|
||||
|
||||
```
|
||||
TDFIX → TDVAL → (if regression or quality drop) → TDFIX-fix → TDVAL-2
|
||||
(if all pass) → report
|
||||
```
|
||||
|
||||
## Unified Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/TD-{slug}-{YYYY-MM-DD}/
|
||||
├── team-session.json
|
||||
├── shared-memory.json # 债务清单 / 评估矩阵 / 治理方案 / 修复结果 / 验证结果
|
||||
├── scan/ # Scanner output
|
||||
│ └── debt-inventory.json
|
||||
├── assessment/ # Assessor output
|
||||
│ └── priority-matrix.json
|
||||
├── plan/ # Planner output
|
||||
│ └── remediation-plan.md
|
||||
├── fixes/ # Executor output
|
||||
│ └── fix-log.json
|
||||
└── validation/ # Validator output
|
||||
└── validation-report.json
|
||||
```
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
```javascript
|
||||
TeamCreate({ team_name: teamName })
|
||||
|
||||
// Scanner
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
team_name: teamName,
|
||||
name: "scanner",
|
||||
prompt: `你是 team "${teamName}" 的 SCANNER。
|
||||
|
||||
## ⚠️ 首要指令（MUST）
|
||||
你的所有工作必须通过调用 Skill 获取角色定义后执行，禁止自行发挥：
|
||||
Skill(skill="team-tech-debt", args="--role=scanner")
|
||||
此调用会加载你的角色定义（role.md）、可用命令（commands/*.md）和完整执行逻辑。
|
||||
|
||||
当前需求: ${taskDescription}
|
||||
约束: ${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 TDSCAN-* 前缀的任务，不得执行其他角色的工作
|
||||
- 所有输出（SendMessage、team_msg）必须带 [scanner] 标识前缀
|
||||
- 仅与 coordinator 通信，不得直接联系其他 worker
|
||||
- 不得使用 TaskCreate 为其他角色创建任务
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
## 工作流程（严格按顺序）
|
||||
1. 调用 Skill(skill="team-tech-debt", args="--role=scanner") 获取角色定义和执行逻辑
|
||||
2. 按 role.md 中的 5-Phase 流程执行（TaskList → 找到 TDSCAN-* 任务 → 执行 → 汇报）
|
||||
3. team_msg log + SendMessage 结果给 coordinator（带 [scanner] 标识）
|
||||
4. TaskUpdate completed → 检查下一个任务 → 回到步骤 1`
|
||||
})
|
||||
|
||||
// Assessor
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
team_name: teamName,
|
||||
name: "assessor",
|
||||
prompt: `你是 team "${teamName}" 的 ASSESSOR。
|
||||
|
||||
## ⚠️ 首要指令（MUST）
|
||||
Skill(skill="team-tech-debt", args="--role=assessor")
|
||||
|
||||
当前需求: ${taskDescription}
|
||||
约束: ${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 TDEVAL-* 前缀的任务
|
||||
- 所有输出必须带 [assessor] 标识前缀
|
||||
- 仅与 coordinator 通信
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
## 工作流程
|
||||
1. Skill(skill="team-tech-debt", args="--role=assessor") 获取角色定义
|
||||
2. TaskList → 找到 TDEVAL-* 任务 → 执行 → 汇报
|
||||
3. team_msg log + SendMessage 结果给 coordinator
|
||||
4. TaskUpdate completed → 检查下一个任务`
|
||||
})
|
||||
|
||||
// Planner
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
team_name: teamName,
|
||||
name: "planner",
|
||||
prompt: `你是 team "${teamName}" 的 PLANNER。
|
||||
|
||||
## ⚠️ 首要指令（MUST）
|
||||
Skill(skill="team-tech-debt", args="--role=planner")
|
||||
|
||||
当前需求: ${taskDescription}
|
||||
约束: ${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 TDPLAN-* 前缀的任务
|
||||
- 所有输出必须带 [planner] 标识前缀
|
||||
- 仅与 coordinator 通信
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
## 工作流程
|
||||
1. Skill(skill="team-tech-debt", args="--role=planner") 获取角色定义
|
||||
2. TaskList → 找到 TDPLAN-* 任务 → 执行 → 汇报
|
||||
3. team_msg log + SendMessage 结果给 coordinator
|
||||
4. TaskUpdate completed → 检查下一个任务`
|
||||
})
|
||||
|
||||
// Executor
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
team_name: teamName,
|
||||
name: "executor",
|
||||
prompt: `你是 team "${teamName}" 的 EXECUTOR。
|
||||
|
||||
## ⚠️ 首要指令（MUST）
|
||||
Skill(skill="team-tech-debt", args="--role=executor")
|
||||
|
||||
当前需求: ${taskDescription}
|
||||
约束: ${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 TDFIX-* 前缀的任务
|
||||
- 所有输出必须带 [executor] 标识前缀
|
||||
- 仅与 coordinator 通信
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
## 工作流程
|
||||
1. Skill(skill="team-tech-debt", args="--role=executor") 获取角色定义
|
||||
2. TaskList → 找到 TDFIX-* 任务 → 执行 → 汇报
|
||||
3. team_msg log + SendMessage 结果给 coordinator
|
||||
4. TaskUpdate completed → 检查下一个任务`
|
||||
})
|
||||
|
||||
// Validator
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
team_name: teamName,
|
||||
name: "validator",
|
||||
prompt: `你是 team "${teamName}" 的 VALIDATOR。
|
||||
|
||||
## ⚠️ 首要指令（MUST）
|
||||
Skill(skill="team-tech-debt", args="--role=validator")
|
||||
|
||||
当前需求: ${taskDescription}
|
||||
约束: ${constraints}
|
||||
|
||||
## 角色准则（强制）
|
||||
- 你只能处理 TDVAL-* 前缀的任务
|
||||
- 所有输出必须带 [validator] 标识前缀
|
||||
- 仅与 coordinator 通信
|
||||
|
||||
## 消息总线（必须）
|
||||
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。
|
||||
|
||||
## 工作流程
|
||||
1. Skill(skill="team-tech-debt", args="--role=validator") 获取角色定义
|
||||
2. TaskList → 找到 TDVAL-* 任务 → 执行 → 汇报
|
||||
3. team_msg log + SendMessage 结果给 coordinator
|
||||
4. TaskUpdate completed → 检查下一个任务`
|
||||
})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown --role value | Error with available role list |
|
||||
| Missing --role arg | Orchestration Mode → auto route to coordinator |
|
||||
| Role file not found | Error with expected path (roles/{name}/role.md) |
|
||||
| Command file not found | Fall back to inline execution in role.md |
|
||||
| Task prefix conflict | Log warning, proceed |
|
||||
| Scanner finds no debt | Report clean codebase, skip to summary |
|
||||
| Fix introduces regression | Trigger Fix-Verify loop (max 3 iterations) |
|
||||
| Validation repeatedly fails | Escalate to user with diagnosis |
|
||||
Reference in New Issue
Block a user