specs-code-cleanup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Cleanup

代码清理

Overview

概述

Performs post-review cosmetic cleanup to make code production-ready. This is the final workflow step after

/specs:task-review

approval.

Input:

docs/specs/[id]/tasks/TASK-XXX.md

(reviewed status)
Output: Cleaned code, task marked

completed

执行审核后的外观性清理，使代码达到生产就绪状态。这是

/specs:task-review

审核通过后的最终工作流程步骤。

输入：

docs/specs/[id]/tasks/TASK-XXX.md

（已审核状态）
输出：清理后的代码，任务标记为

completed

When to Use

使用场景

Use when asked to clean up code, polish, finalize, tidy up, or remove technical debt after review approval.
Use to prepare code for completion: remove debug logs, dead code, optimize imports, and improve readability.
Use as the final quality gate in the specification-driven development workflow.
Not for refactoring logic or fixing bugs — focused solely on cosmetic and hygiene cleanup.

当审核通过后，被要求清理代码、打磨代码、完成收尾、整理代码或消除技术债务时使用。
用于为代码完成做准备：移除调试日志、死代码，优化导入并提升可读性。
作为规范驱动开发工作流程中的最终质量关卡。
不用于重构逻辑或修复bug——仅专注于代码的外观和整洁性清理。

Arguments

参数

Argument	Required	Description
`--lang`	No	`java` , `spring` , `typescript` , `nestjs` , `react` , `python` , `general`
`--task`	Yes	Path to task file

参数	是否必填	描述
`--lang`	否	`java` , `spring` , `typescript` , `nestjs` , `react` , `python` , `general`
`--task`	是	任务文件路径

Best Practices

最佳实践

Clean, not change: Only remove or reorganize — never change functionality
Preserve behavior: Code must work exactly the same after cleanup

Use project tools: Prefer

./mvnw spotless:apply

npm run lint:fix

black

, etc.

Use TodoWrite: Track progress through all 8 phases
Stop on failure: If tests fail, stop and report — do not proceed

See

references/language-patterns.md

for language-specific formatter commands, import ordering, and grep patterns.

只清理，不修改：仅移除或重新组织代码——绝不改变功能
保留原有行为：清理后的代码必须与之前完全一致
使用项目工具：优先使用
```
./mvnw spotless:apply
```
,
```
npm run lint:fix
```
,
```
black
```
等工具
使用TodoWrite：跟踪所有8个阶段的进度
失败即停止：如果测试失败，立即停止并报告——不要继续执行

查看

references/language-patterns.md

获取特定语言的格式化命令、导入排序规则和grep模式。

Instructions

操作步骤

Phase 1: Task Verification

阶段1：任务验证

Parse
```
$ARGUMENTS
```
for parameters:
- ```
--lang
```
  (optional): Target language/framework
- ```
--task
```
  (required): Task ID or file path
- ```
--spec
```
  (optional): Spec folder path (used with task ID)
Support two formats:
- Format 1 (direct path):
```
--task=docs/specs/001-feature/tasks/TASK-001.md
```
- Format 2 (spec+task):
```
--spec=docs/specs/001-feature --task=TASK-001
```
If Format 2 is used, construct the task file path as:
```
{spec}/tasks/{task}.md
```
Read the task file. Verify:
- Status is
```
reviewed
```
  or
```
implemented
```
  (not
```
completed
```
  )
- Review report
```
TASK-XXX--review.md
```
  exists and is approved
If not reviewed → stop and tell user to run
```
/specs:task-review
```
first
Extract task ID, title, and
```
provides
```
files

解析
```
$ARGUMENTS
```
获取参数：
- ```
--lang
```
  （可选）：目标语言/框架
- ```
--task
```
  （必填）：任务ID或文件路径
- ```
--spec
```
  （可选）：规范文件夹路径（与任务ID配合使用）
支持两种格式：
- 格式1（直接路径）：
```
--task=docs/specs/001-feature/tasks/TASK-001.md
```
- 格式2（规范+任务）：
```
--spec=docs/specs/001-feature --task=TASK-001
```
如果使用格式2，任务文件路径构造为：
```
{spec}/tasks/{task}.md
```
读取任务文件，验证：
- 状态为
```
reviewed
```
  或
```
implemented
```
  （非
```
completed
```
  ）
- 审核报告
```
TASK-XXX--review.md
```
  已存在且已通过审核
如果未审核 → 停止并告知用户先运行
```
/specs:task-review
```
提取任务ID、标题和
```
provides
```
字段中的文件

Phase 2: Identify Files to Clean

阶段2：确定待清理文件

Read
```
TASK-XXX--review.md
```
for files created/modified
Read task
```
provides
```
field for file paths
Verify files exist; build cleanup list
Categorize: source files, test files, config files

读取
```
TASK-XXX--review.md
```
获取创建/修改的文件
读取任务的
```
provides
```
字段获取文件路径
验证文件存在；构建清理列表
分类：源文件、测试文件、配置文件

Phase 3: Technical Debt Removal

阶段3：技术债务消除

Search files for temporary/debug artifacts with Grep:

console.log

System.out.println

print(

// DEBUG:

// temp

// hack

Resolved
```
TODO
```
/
```
FIXME
```
comments (keep unresolved ones)

Review context for each finding. Remove confirmed debt and document what was removed.

使用Grep搜索文件中的临时/调试产物：

console.log

System.out.println

print(

// DEBUG:

// temp

// hack

已解决的
```
TODO
```
/
```
FIXME
```
注释（保留未解决的）

查看每个结果的上下文，移除确认的技术债务并记录移除内容。

Phase 4: Import Optimization

阶段4：导入优化

Run language-specific import optimizer if available (see references)
Manually remove unused imports if no tool exists
Document files changed

如果有可用的特定语言导入优化工具，运行该工具（参考文档）
如果没有工具，手动移除未使用的导入
记录修改的文件

Phase 5: Code Readability Improvements

阶段5：代码可读性提升

Run language-specific formatter if available (see references)
If no formatter: fix indentation, break long lines (>120), fix spacing
Remove dead code only if obviously safe
Document changes

如果有可用的特定语言格式化工具，运行该工具（参考文档）
如果没有格式化工具：修复缩进、拆分过长行（>120字符）、修正空格
仅在明显安全的情况下移除死代码
记录修改内容

Phase 6: Documentation Verification

阶段6：文档验证

Verify class/file headers and public API docs
Check remaining TODOs are still valid and have context
Remove or update outdated comments
Document documentation changes

验证类/文件头部和公共API文档
检查剩余的TODO是否仍然有效且有上下文
移除或更新过时的注释
记录文档修改内容

Phase 7: Final Verification

阶段7：最终验证

Run linters if available
Run tests if available
Verify no logic or signature changes were introduced
If tests fail → stop and report failures

如果有可用的代码检查工具，运行该工具
如果有可用的测试，运行测试
验证未引入逻辑或签名变更
如果测试失败 → 停止并报告失败情况

Phase 8: Task Completion

阶段8：任务完成

Auto-update task status:
- Add a
```
## Cleanup Summary
```
  section to the task file
- Check any remaining boxes in the DoD section
- Hooks automatically update status to
```
completed
```
  and set
```
completed_date
```
  +
```
cleanup_date
```
Append
```
## Cleanup Summary
```
to task file with:
- Files cleaned
- Changes made
- Verification checklist (linters, tests, no functionality changes)
Mark all todos complete

自动更新任务状态：
- 在任务文件中添加
```
## 清理摘要
```
  章节
- 勾选DoD章节中剩余的所有选项
- 钩子会自动将状态更新为
```
completed
```
  并设置
```
completed_date
```
  和
```
cleanup_date
```
在任务文件末尾追加
```
## 清理摘要
```
，包含：
- 已清理的文件
- 所做的修改
- 验证清单（代码检查、测试、无功能变更）
标记所有待办事项为完成

Examples

示例

Spring Boot Cleanup

Spring Boot 代码清理

bash

/developer-kit-specs:specs-code-cleanup --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"

Actions:

Verify TASK-001 status is
```
reviewed
```

Files:

UserController.java

UserService.java

UserRepository.java

Remove 5
```
System.out.println
```
and 2 resolved TODOs
Run
```
./mvnw spotless:apply
```
Run
```
./mvnw test -q
```
Mark task
```
completed
```

bash

/developer-kit-specs:specs-code-cleanup --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"

操作：

验证TASK-001状态为
```
reviewed
```

文件：

UserController.java

UserService.java

UserRepository.java

移除5条
```
System.out.println
```
和2条已解决的TODO
运行
```
./mvnw spotless:apply
```
运行
```
./mvnw test -q
```
将任务标记为
```
completed
```

TypeScript Cleanup

TypeScript 代码清理

bash

/developer-kit-specs:specs-code-cleanup --lang=typescript --task="docs/specs/002-dashboard/tasks/TASK-003.md"

Actions:

Verify TASK-003 status is
```
reviewed
```

Files:

Dashboard.tsx

useDashboard.ts

Dashboard.test.tsx

Remove 8
```
console.log
```
statements
Run
```
npm run lint:fix
```
and
```
npm run format
```
Run
```
npm test
```
Mark task
```
completed
```

bash

/developer-kit-specs:specs-code-cleanup --lang=typescript --task="docs/specs/002-dashboard/tasks/TASK-003.md"

操作：

验证TASK-003状态为
```
reviewed
```

文件：

Dashboard.tsx

useDashboard.ts

Dashboard.test.tsx

移除8条
```
console.log
```
语句
运行
```
npm run lint:fix
```
和
```
npm run format
```
运行
```
npm test
```
将任务标记为
```
completed
```

Constraints and Warnings

约束与警告

Never change logic or signatures during cleanup
Stop immediately and report if tests fail
Verify behavior is unchanged before marking complete

清理过程中绝不能修改逻辑或签名
如果测试失败，立即停止并报告
在标记完成前验证行为未发生改变