name: clean-project
description: 自动分析项目并执行结构化清理（删除无用文件、归位错放文件、合并重复目录、规范命名、整理 docs 与 .gitignore），静默执行不输出分析报告。
tags: [eng-standards, devops]
version: 1.0.0
recommended_scope: project

Skill: 清理项目 (Clean Project)

目的 (Purpose)

在不输出任何分析报告或文档的前提下，对当前项目执行必要的结构化清理：删除无用/重复/缓存/临时/构建产物、归位错放文件、合并重复目录、规范命名、整理 docs/ 与 .gitignore，使仓库结构高内聚、低耦合、符合惯用布局。

适用场景 (Use Cases)

• 日常维护：仓库积累大量临时文件、错误放置的文档或重复目录，需要一次性静默整理。
• 移交前整理：项目移交或开源前，统一目录规范与命名、清理不应纳入版本控制的内容。
• CI/本地预检：在提交或 CI 前自动执行清理，确保仓库保持整洁。

何时使用：当用户触发「清理项目」或 /auto-clean-project 且要求直接对文件系统执行修改、不产出分析文档时。

行为要求 (Behavior)

执行原则

• 静默模式：不输出结构分析、诊断报告、示例结构或 Todo List；所有判断在内部完成。
• 直接修改：仅通过实际的文件/目录操作（删除、移动、重命名、写入）呈现变更；以 Cursor 的 Apply Changes（diff）或等价形式展示结果。
• 无变更时：若经分析无需任何修改，则仅返回一句：「No changes required.」

必须执行的操作（按需应用）

1. 删除：无意义、重复、空目录、缓存、日志、临时、构建产物、大文件/二进制（若不应入库）、IDE 配置目录（如 .idea 等，按项目约定）等。
2. 移动：放错位置的文件（如根目录的 DATABASE.md、QUICKSTART.md → docs/ 或相关目录）。
3. 合并与精简：重复目录合并、移除冗余层级、清理混乱结构。
4. 重命名：不规范的目录与文件名（蛇形、短横线、大小写不一致等）统一为项目约定（通常 kebab-case）。
5. 重组：按高内聚、低耦合、就近原则重新组织文件。
6. .gitignore：自动生成或更新，排除常见临时/构建/本地配置。
7. 大文件/二进制：识别并移除不应纳入仓库的内容（不执行 git-filter-repo，需用户确认）。
8. docs/：若不存在则创建；整理文档结构（如按主题分子目录）。
9. 语言惯用结构：为语言特定项目添加惯用结构（如 Python 的 src/、Node 的 src/、Go 的 cmd/ 等），仅当当前项目明显为该语言且缺失时。

Git 仓库额外约定

• 若发现 .git：自动生成或补充 .gitignore；清理 .DS_Store、常见临时文件等。
• 禁止在未获用户确认的情况下执行 git-filter-repo 或等价历史重写操作。

输入与输出 (Input & Output)

输入 (Input)

• 工作区根：当前 Agent 或命令的工作区根目录（即项目根）。
• 可选：用户通过命令参数或上下文声明的「保留目录/文件」或「禁止删除的路径」（若有则严格遵守）。

输出 (Output)

• 有变更：仅展示对文件系统的实际变更（如 Apply Changes diff），无文字分析或报告。
• 无变更：仅一句：「No changes required.」

禁止行为 (Restrictions)

• 禁止输出结构分析、诊断报告、示例结构、Todo List 或「建议」类文字。
• 禁止在未获用户明确确认的情况下执行 git-filter-repo 或任何会重写 Git 历史的操作。
• 禁止删除未在技能中明确允许删除的类型时擅自删除（如用户源码、配置源文件）；有歧义时以保留为优先。

质量检查 (Self-Check)

• [ ] 是否未输出任何分析、报告或 Todo？
• [ ] 有修改时是否仅通过文件系统变更（diff）呈现？
• [ ] 无修改时是否仅返回「No changes required.»？
• [ ] 是否未执行 git-filter-repo 等历史重写？
• [ ] .gitignore 是否已按需生成或更新且未误删必要条目？

示例 (Examples)

示例一：常规清理

• 输入：项目根下存在 tmp/、*.log、根目录 QUICKSTART.md、无 docs/。
• 预期行为：删除 tmp/ 与匹配的 *.log；将 QUICKSTART.md 移至 docs/quickstart.md（或等价）；创建 docs/ 若不存在；更新 .gitignore 加入 *.log、tmp/ 等。仅输出 diff，无文字说明。

示例二：无变更

• 输入：项目已整洁，无冗余文件、无错放文档、.gitignore 已完善。
• 预期行为：仅返回：「No changes required.»

边界示例：存在 .git 且含大文件

• 输入：仓库内存在不应入库的大二进制文件，已被跟踪。
• 预期行为：可更新 .gitignore 以防未来再次加入；不自动执行 git-filter-repo；若需从历史中移除，须在输出中仅以一句提示需用户确认后再执行，且不自动执行。