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
|