---
name: style-cleanup
description:
  "Clean up formatting and code style with the repo’s existing toolchain
  (clang-format/black/isort/flake8/pre-commit/etc). Triggers: 整理代码风格,
  格式化, format, fmt, lint fix, clang-format, black, isort."
---

# Style Cleanup Workflow（整理代码风格 / 格式化）

## When to Use

- “整理代码风格 / 格式化 / format / fmt / lint fix”
- 合并前做一次风格对齐（不做语义级重构）
- 批量改动后，希望把格式化与机械性风格问题收敛到可控 diff

## Inputs（required）

- Scope：仅本次改动文件（默认）｜全仓库｜指定目录/文件类型
- Languages：自动识别；如为多语言仓库请确认优先级
- Verification：至少一个可执行的验证命令（如未知，先问/再推断）

## Procedure（default）

1. **Baseline**

   - 记录当前状态：`git status --porcelain`
   - 明确范围（默认只处理变更文件）：
     - staged：`git diff --name-only --cached`
     - unstaged：`git diff --name-only`
     - untracked：`git ls-files -o --exclude-standard`

2. **Detect Toolchain（prefer repo truth）**

   - 优先用仓库既有入口脚本 / 配置：
     - JS/TS：`package.json`
       scripts（`format`/`lint`/`lint:fix`）、prettier/biome/eslint 配置
     - Python：`pyproject.toml` / `.flake8` / `.pylintrc` /
       `.pre-commit-config.yaml`
     - C/C++：`.clang-format`（唯一真相），可选 `.clang-tidy`
     - Shell：`shfmt`/`shellcheck`（若仓库已使用）
     - Markdown：prettier/markdownlint（仅在仓库已固定时使用）
   - 禁止默认“引入新 formatter/linter 配置”；缺配置时只做最小手工调整，并先确认是否允许落地配置文件。

3. **Apply（format first, then lint）**

   - 先 formatter（会改文件），再 lint（检查），再 lint
     --fix（如有），最后再跑一次 check 确认干净。
   - 默认只处理目标文件集合；避免全仓库 reformat（除非用户明确要求）。
   - 典型命令（按仓库实际替换）：
     - C++：`clang-format -i <files...>`；CI 校验：`clang-format --dry-run --Werror <files...>`
     - Python：`black <files...>` + `isort <files...>`；或
       `pre-commit run --files <files...>`
     - JS/TS：`npm run format -- <files...>` / `pnpm ...` /
       `npx prettier -w <files...>`（以项目脚本为准）

4. **Guardrails**

   - 只做风格与格式：不改变行为、不改 public API、不做重构。
   - 如格式化导致 diff 暴涨（文件数/行数过大）：先停下，给出原因与两种方案让用户选：
     1. 仅格式化本次改动文件（推荐默认）
     2. 全仓库统一格式（通常需要单独 PR/提交）

5. **Verify**
   - 跑最小验证命令（仓库已有命令优先）。
   - 若无法运行（缺环境/缺权限/缺依赖）：说明原因，并给出替代验证（例如 formatter 二次运行无 diff、lint 输出为 0）。

## Playbook as Authority（如果项目 vendoring 了本 Playbook）

当目标仓库包含 `docs/standards/playbook/docs/`（或直接包含
`docs/tsl|cpp|python/...`），风格决策参考：

- TSL：`docs/tsl/code_style.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md`
- C++：`docs/cpp/code_style.md`、`docs/cpp/naming.md`、`docs/cpp/toolchain.md`
- Python：`docs/python/style_guide.md`、`docs/python/tooling.md`、`docs/python/configuration.md`

## Output Contract（stable）

- Scope：实际处理范围（文件/目录/语言）
- Toolchain：使用了哪些工具与配置依据
- Commands：实际执行命令（按顺序）
- Changes：修改文件列表 + 改动规模概览
- Remaining：仍未修复的问题（分类：formatter / lint / style）+ 下一步建议

## Success Criteria

- formatter 二次运行无新增 diff
- lint/检查命令通过（或仅剩已确认的例外）
- 未引入语义变更（仅格式/风格）

## Failure Handling

- 工具缺失：优先提示安装方式或替代命令；无法解决则退回“最小手工风格修复 + 明确未覆盖项”
- 规则冲突（如 black vs flake8）：以仓库配置为准；必要时调整例外配置但需先确认