safe-project-organizer

安全项目整理器

概述

此技能可让 Claude Code 分析项目结构，并提出安全的整理改进建议，例如移动文件、删除未使用的目录和重组文件夹。它通过多阶段验证、试运行预览和明确的用户确认来优先保障安全。

核心安全原则

1. 只读分析阶段

• 所有分析操作均为只读
• 扫描期间不会进行任何修改
• 在进行任何更改前，先完整快照项目

2. 试运行验证

• 执行前预览所有操作的更改
• 显示受影响文件的确切路径
• 计算影响指标（移动、删除和创建的文件数）

3. 明确的用户确认

• 每类操作都需要确认
• 显示详细的更改摘要
• 允许选择性批准建议

4. 支持回滚的原子操作

• 每项操作均可撤销
• 修改前创建备份引用
• 保留操作日志以供审计

5. 受保护的文件模式

绝不修改匹配以下模式的文件：

• .git/、.svn/、.hg/（版本控制）
• node_modules/、vendor/、venv/、.venv/（依赖项）
• .env*、secrets.*、credentials.*（敏感数据）
• package-lock.json、yarn.lock、pnpm-lock.yaml（锁定文件）
• dist/、build/、.next/、.nuxt/（构建产物）

何时使用此技能

遇到以下任何情况时，请使用此技能：

项目清理：

• “我的项目根目录里文件太多，乱糟糟的”
• “我有一些空目录，应该清理掉”
• “文档文件散落得到处都是”

标准化：

• “这个项目没有遵循标准目录结构”
• “源文件和配置文件混在根目录里”
• “我需要按类型整理文件，以便更好地维护”

迁移准备：

• “我准备移交这个项目，需要先整理一下”
• “添加新功能前，这个代码库需要更好的组织结构”
• “我想统一项目结构”

安全顾虑：

• “我担心不小心弄坏什么”
• “我需要在更改前准确查看会发生什么变化”
• “我想安全地重新整理项目，同时不丢失数据”

安全使用工作流

第 1 步：初始扫描（只读）

使用 --scan 标志执行项目整理器脚本：

python3 scripts/project_organizer.py /path/to/project --scan

执行内容：

• 扫描整个项目结构
• 识别文件类型、数量和大小
• 检测空目录
• 列出受保护的文件
• 不会进行任何修改

输出示例：

🔍 Scanning project: /path/to/project
📋 This is a READ-ONLY scan. No changes will be made.

✅ Scan complete!
   📁 Directories: 24
   📄 Files: 156
   🔒 Protected items: 42
   📂 Empty directories: 3

第 2 步：生成建议（仍为只读）

使用 --analyze 标志生成整理建议：

python3 scripts/project_organizer.py /path/to/project --analyze

执行内容：

• 执行完整分析
• 生成整理建议
• 显示建议数量
• 仍不会进行任何修改

第 3 步：预览更改（详细审查）

使用 --preview 标志准确查看将发生的更改：

python3 scripts/project_organizer.py /path/to/project --preview

执行内容：

• 显示所有建议的详细预览
• 按操作类型分组（移动、删除、创建）
• 显示风险级别（🟢 低、🟡 中、🔴 高）
• 显示每项操作的安全检查
• 列出受影响文件的确切路径
• 不会进行任何修改

预览输出示例：

📋 PREVIEW MODE - No changes will be made
============================================================

📊 Total Suggestions: 8

🎯 By Action:
   MOVE: 5
   DELETE: 2
   CREATE_DIR: 1

⚠️  By Risk Level:
   🟢 LOW: 6
   🟡 MEDIUM: 2

📝 Detailed Suggestions:

MOVE Operations (5):
1. 🟢 Documentation/config files organized in docs/ directory
   FROM: CONTRIBUTING.md
   TO:   docs/CONTRIBUTING.md
   Safety Checks:
      ✓ File is not a primary config
      ✓ No imports reference this file path
      ✓ Not in protected patterns

DELETE Operations (2):
1. 🟢 Empty directory with no files or subdirectories
   PATH: old_backup/temp
   Safety Checks:
      ✓ Directory is empty
      ✓ Not a protected path
      ✓ No version control markers

第 4 步：试运行（仅模拟）

使用 --execute 标志进行试运行模拟：

python3 scripts/project_organizer.py /path/to/project --execute

执行内容：

• 模拟所有操作
• 显示将会发生的情况
• 验证所有安全检查
• 报告成功、失败或跳过的操作
• 不会实际更改任何内容

第 5 步：实际执行（需要确认）

经过全面审查后，才使用 --execute-real 标志：

python3 scripts/project_organizer.py /path/to/project --execute-real

执行内容：

• 提示进行明确确认
• 执行已批准的更改
• 创建审计日志（.project_organizer.log）
• 实时显示进度
• 实际修改项目

确认提示：

⚠️  WARNING: This will make REAL changes. Type 'yes' to confirm: yes

操作类型与安全性

移动操作

低风险（🟢）：

• 将文档文件移至 docs/
• 将配置文件移至 config/
• 将脚本移至 scripts/

中风险（🟡）：

• 按类型对源文件分组
• 创建组织目录

已执行的安全检查：

• 源文件存在且可访问
• 源路径不符合受保护模式
• 目标位置尚不存在
• 可以安全地创建父目录

删除操作

低风险（🟢）：

• 移除真正的空目录
• 删除临时文件

已执行的安全检查：

• 目标存在
• 目录完全为空
• 不是受保护路径
• 不含版本控制标记

创建目录操作

低风险（🟢）：

• 创建标准目录（src/、docs/、tests/）
• 创建组织结构

已执行的安全检查：

• 目标尚不存在
• 不存在命名冲突
• 符合标准目录模式
• 可以创建父目录

受保护的文件模式

此技能会自动保护以下路径，防止其被修改：

版本控制

• .git/、.git/**
• .svn/、.svn/**
• .hg/、.hg/**

依赖项

• node_modules/、node_modules/**
• vendor/、vendor/**
• venv/、venv/**
• .venv/、.venv/**

构建产物

• dist/、dist/**
• build/、build/**
• .next/、.next/**
• .nuxt/、.nuxt/**
• out/、out/**

敏感数据

• .env*
• secrets.*
• credentials.*

锁定文件

• package-lock.json
• yarn.lock
• pnpm-lock.yaml
• Gemfile.lock
• Pipfile.lock
• poetry.lock

缓存文件

• __pycache__/、__pycache__/**

最佳实践

运行此技能前

1. 提交更改：确保所有当前工作都已提交到版本控制
2. 备份重要文件：准备近期备份或可用的 git stash
3. 检查项目：了解哪些文件和目录很重要
4. 测试访问权限：确认你拥有必要的权限

执行期间

1. 始终先扫描：使用 --scan 开始，以了解项目情况
2. 仔细检查建议：查看生成的所有建议
3. 使用预览模式：执行任何操作前，务必使用 --preview
4. 进行试运行：使用 --execute 安全地模拟更改

执行后

1. 验证项目正常运行：测试项目仍可正常构建和运行
2. 检查操作日志：查看 .project_organizer.log，了解更改内容
3. 单独提交：将组织结构更改与功能更改单独提交
4. 更新文档：更新所有引用旧文件路径的文档

安全检查清单

使用 --execute-real 前，请确认：

• 项目已提交到版本控制
• 已在预览模式下检查所有建议
• 试运行已成功完成
• 未移动任何关键文件
• 构建和测试流程仍正常运行
• 如果项目由多人共享，已通知团队成员

错误处理与故障排除

常见问题

权限被拒绝：

• 确保你拥有写入权限
• 检查文件所有权
• 可能需要相应的权限

路径受保护：

• 检查受保护模式
• 确认该路径是否应该被修改
• 如有需要，调整模式

更改未显示：

• 确认使用了 --execute-real（而不只是 --execute）
• 检查操作日志
• 确认在确认提示处输入了“yes”

恢复选项

Git 恢复：

git status                    # See what changed
git checkout -- .            # Restore all changes
git reset --hard HEAD        # Full reset to last commit

查看操作日志：

cat .project_organizer.log    # Review detailed operation log

自定义

添加自定义受保护模式

编辑脚本中的 PROTECTED_PATTERNS 列表：

PROTECTED_PATTERNS = [
    # Existing patterns...
    'my_important_dir/**',    # Custom protection
    '*.critical',             # Protect critical files
]

自定义组织规则

编辑 MOVABLE_ROOT_FILES 字典：

MOVABLE_ROOT_FILES = {
    'assets': ['*.png', '*.jpg', '*.svg'],  # Move images to assets/
    'data': ['*.csv', '*.json', '*.xml'],   # Move data files
}

自定义安全验证器

扩展 SafeProjectOrganizer 类：

def _custom_safety_check(self, path: Path) -> bool:
    """Your custom safety logic"""
    # Return True if safe, False if should be protected
    return True

与 Claude Code 集成

作为技能工具

此技能可自然融入 Claude Code 的工作流：

1. 用户请求：「整理我的项目结构」
2. 技能激活：加载 Safe Project Organizer
3. 按序执行：自动遵循 5 步工作流
4. 用户确认：每一步继续前都进行确认
5. 安全验证：所有操作都包含安全检查

用户交互示例

简单清理：

User: "My project root is messy, can you help organize it?"
Claude: [Uses skill to scan and suggest safe improvements]

针对性整理：

User: "I have too many documentation files scattered around"
Claude: [Uses skill to identify and suggest grouping docs/ folder]

迁移前清理：

User: "I need to clean up before handing this project to another team"
Claude: [Uses skill for comprehensive safe reorganization]

资源

scripts/

• project_organizer.py - 具备全面安全功能的主要安全项目整理脚本

该脚本包含：

• 多阶段分析与执行
• 受保护模式检测
• 风险级别分类
• 全面的安全检查
• 审计跟踪生成
• 回滚信息保留

此脚本可独立于 Claude Code 执行，用于手动整理项目。

---

安全保证：此技能绝不会在未获得明确确认的情况下修改文件，始终会预览更改，并包含全面的安全检查，以保护重要项目数据。

---

用户验证强制要求

政策：未经用户确认，不得声称问题已修复

重要：在声称任何问题、错误或故障已「修复」「解决」「正常运行」或「完成」之前，必须遵循以下验证流程：

第 1 步：技术验证

• 运行所有相关测试（构建、类型检查、单元测试）
• 验证没有控制台错误
• 截取修复的屏幕截图或留存证据

第 2 步：请求用户验证

必须：使用 AskUserQuestion 工具，明确询问用户是否验证了修复：

"I've implemented [description of fix]. Before I mark this as complete, please verify:
1. [Specific thing to check #1]
2. [Specific thing to check #2]
3. Does this fix the issue you were experiencing?

Please confirm the fix works as expected, or let me know what's still not working."

第 3 步：等待用户确认

• 用户回复前，不得声称已成功
• 未经用户确认，不得将任务标记为「已完成」
• 未经用户验证，不得使用「已修复」「已解决」「正常运行」等表述

第 4 步：处理用户反馈

• 如果用户确认：记录修复并标记为完成
• 如果用户报告问题：继续调试，并重复验证流程

未经用户验证时禁止的操作

• 声称错误已「修复」
• 表示功能「正常运行」
• 将问题标记为「已解决」
• 宣布功能「已完成」
• 对修复作出任何成功声明

请求用户验证前必须提供的证据

1. 技术测试通过
2. 通过 Playwright/屏幕截图进行视觉确认
3. 已执行具体测试场景
4. 清楚说明更改内容

请记住：用户是判断问题是否已修复的最终权威。没有例外。