108 lines
3.8 KiB
Markdown
108 lines
3.8 KiB
Markdown
---
|
||
name: style-cleanup
|
||
description: Use when the user asks to format code, fix lint issues, or align style with the repository's existing toolchain without changing behavior.
|
||
---
|
||
|
||
# Style Cleanup Workflow（整理代码风格 / 格式化）
|
||
|
||
## Overview
|
||
|
||
Apply the repository's existing formatter and lint toolchain without changing
|
||
behavior. Core principle: trust repo truth, keep scope tight, and verify with a
|
||
rerun.
|
||
|
||
## When to Use
|
||
|
||
- The user asks for formatting, `fmt`, `format`, or lint cleanup
|
||
- A code change is done and needs a final style pass before review or commit
|
||
- A mechanical change produced noisy diff that should be normalized by the repo's
|
||
existing toolchain
|
||
|
||
## When Not to Use
|
||
|
||
- This is not for semantic refactors or behavior changes
|
||
- This is not for introducing a new formatter or lint configuration
|
||
- This is not for full-repo reformatting unless the user explicitly requests that
|
||
scope
|
||
|
||
## Inputs
|
||
|
||
- Target scope: staged files, unstaged files, explicit file list, or explicit
|
||
directory
|
||
- Relevant languages in scope
|
||
- Verification commands available in the repository
|
||
|
||
## Procedure
|
||
|
||
1. **Baseline the scope**
|
||
|
||
- Record `git status --short`.
|
||
- Default to changed files only unless the user requested broader scope.
|
||
- Resolve the target file set before running any formatter.
|
||
|
||
2. **Detect the repo toolchain**
|
||
|
||
- Prefer repository scripts and checked-in config over ad hoc commands.
|
||
- Use the repo's existing formatter/linter stack:
|
||
- JS/TS: `package.json`, prettier, biome, eslint
|
||
- Python: `pyproject.toml`, `isort`, `black`, `ruff`, `flake8`,
|
||
`pre-commit`
|
||
- C/C++: `.clang-format`, optional `.clang-tidy`
|
||
- Shell: `shfmt`, `shellcheck` if already present
|
||
- Markdown: prettier/markdownlint only if the repo already uses them
|
||
|
||
3. **Run cleanup in a fixed loop**
|
||
|
||
- Use `formatter -> lint/check -> lint --fix -> final check`.
|
||
- Prefer repository entrypoints over raw tool invocations.
|
||
- Keep execution scoped to the chosen files whenever the toolchain supports it.
|
||
|
||
4. **Control blast radius**
|
||
|
||
- If the formatter expands the diff far beyond the requested scope, stop and
|
||
explain the tradeoff.
|
||
- Offer a scoped pass vs. a full-repo normalization pass instead of silently
|
||
widening scope.
|
||
|
||
5. **Verify**
|
||
|
||
- Re-run the lightweight checks after fixes.
|
||
- Confirm that the second formatter run produces no additional diff.
|
||
- If the repo has a canonical lint or test command for style verification, run
|
||
that command and report the result.
|
||
|
||
## Playbook as Authority
|
||
|
||
When the target repo vendors this playbook, prefer these references for style
|
||
judgment:
|
||
|
||
- 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
|
||
|
||
- `Scope:` actual files/directories/languages processed
|
||
- `Toolchain:` repo configs and commands used
|
||
- `Commands:` execution order
|
||
- `Changes:` modified files plus diff-size summary
|
||
- `Remaining:` unresolved lint/style issues plus why they remain
|
||
|
||
## Success Criteria
|
||
|
||
- Style cleanup stays within the requested or agreed scope
|
||
- The second formatter run produces no additional diff
|
||
- Verification commands pass, or any remaining exception is explicitly explained
|
||
- No semantic behavior change is introduced
|
||
|
||
## Failure Handling
|
||
|
||
- If the repo lacks a formatter/linter, say so and fall back to minimal manual
|
||
cleanup only with clear limits
|
||
- If tools are missing locally, report the missing dependency and stop before
|
||
inventing a new toolchain
|
||
- If two configured tools conflict, follow checked-in repo config and surface the
|
||
conflict instead of papering over it
|
||
- If cleanup would require wider scope than requested, stop and ask for approval
|