mcpField
F
folder-organization

folder-organization

github.com/delphine-l开发22148 次安装24 周前更新
代码仓库

关于 folder-organization

一项用于整理项目目录、制定文件命名规则并提升项目可导航性的指导技能，面向研究与开发工作。它提供不同项目类型的结构范例，以及版本控制、重组和文档维护流程。

主要功能

  1. 01提供研究和开发项目结构建议
  2. 02制定文件与目录命名规范
  3. 03区分原始、处理中和外部数据
  4. 04指导版本控制与忽略文件管理
  5. 05提供重组和弃用流程
  6. 06组织项目文档与清单文件

适用场景

  1. 01搭建新的研究项目目录
  2. 02重组现有代码库
  3. 03统一团队文件命名方式
  4. 04清理生成文件或弃用文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/delphine-l/claude_global --skill folder-organization

安装后在 Claude Code 中输入/folder-organization确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

deprecation-guide.md
documentation-organization.md
manifest-system.md
naming-conventions.md
project-structures.md
reorganization-guide.md

详细介绍

文件夹组织最佳实践

专家指导，帮助您组织项目目录、建立文件命名规范，并为研究和开发工作维护整洁、易于浏览的项目结构。

何时使用此技能

  • 创建新项目
  • 重新组织现有项目
  • 建立团队规范
  • 创建可复现的研究结构
  • 管理数据密集型项目

核心原则

  1. 可预测性——为常见文件类型设定标准位置
  2. 可扩展性——项目发展时，结构也能平稳扩展
  3. 关注点分离——将代码、数据、文档和输出分开
  4. 易于查找——方便他人（以及未来的自己）浏览
  5. 适合版本控制——恰当地排除大型文件和生成文件

快速参考：标准项目结构

选择与项目类型匹配的结构。完整模板请参阅 project-structures.md。

研究/分析：data/{raw,processed,external}、notebooks/、src/、scripts/、tests/、docs/、results/、config/

开发：src/package_name/、tests/、docs/、examples/、.github/workflows/

生物信息学：data/{raw,reference,processed}、workflows/、config/、scripts/、results/、logs/

使用笔记本进行数据分析：notebooks/、figures/、data/、tests/、scripts/、docs/、archives/

添加 MANIFEST.md 文件，以便高效浏览（参阅 manifest-system.md）。

文件命名规则

详细规范请参阅 naming-conventions.md。关键规则：

  1. 使用小写字母，并用连字符或下划线分隔（不要使用空格或驼峰命名）
  2. 名称要具体且简洁——使用 process-telomere-data.py，而不是 script.py
  3. 统一分隔符——文件名使用连字符，Python 模块名使用下划线
  4. 为重要输出添加版本/日期——report-2026-01-23.pdf
  5. 序号补零——01-exploration.ipynb、02-analysis.ipynb
  6. 统一 session-saves/ 目录中的会话笔记格式

版本控制

应提交：源代码、文档、配置文件、小型测试数据（<1MB）、依赖文件、README 文件

不要提交：大型数据文件、生成的输出、环境目录、日志、临时文件、API 密钥/机密信息

.gitignore 模板
# Claude Code
.claude/

# Python
__pycache__/
*.py[cod]
.venv/
venv/

# Jupyter
.ipynb_checkpoints/

# Data
data/raw/
data/processed/
*.fastq.gz
*.bam

# Outputs
results/
outputs/
*.png
*.pdf

# Logs & Environment
logs/
*.log
.env
.DS_Store

数据组织

  • 绝不修改原始数据——将原始文件保存在 data/raw/ 中（尽可能设为只读）
  • 记录数据来源信息（来源、下载日期）
  • 使用层级结构：raw/ -> interim/ -> processed/ -> external/

常见反模式

避免以下做法：

  • 结构扁平：所有内容都放在根目录，没有任何组织
  • 命名含糊：notebook1.ipynb、test.ipynb、analysis_new.ipynb
  • 关注点混杂：在 src/ 目录中混放数据文件和输出图像

弃用策略

弃用而非删除，以保留历史记录并提供恢复选项。完整指南请参阅 deprecation-guide.md。

关键做法：

  1. 创建 deprecated/ 子目录，并使用描述性名称
  2. 将旧文件移入其中
  3. 编写 README.md，说明弃用了什么、何时弃用、为何弃用以及如何恢复
  4. 如果弃用目录散落各处，将其统一整理到根目录下的 deprecated/

项目重组

完整的系统指南请参阅 reorganization-guide.md。关键步骤：

  1. 移动文件后，更新脚本和笔记本中的所有文件路径
  2. 搜索引用：grep -r "\.json\|\.csv\|\.png" --include="*.ipynb" --include="*.py"
  3. 核对文件数量是否符合预期（确保没有文件丢失）
  4. 移除临时文件（.bak、.ipynb_checkpoints）
  5. 测试笔记本/脚本是否仍能正常运行

文档规范

完整指南请参阅 documentation-organization.md。要点：

  • 每个项目都需要 README，包含：描述、安装、用法、结构、数据、结果
  • 重大变更后，创建带日期的摘要文档
  • 将散落的文档统一整理到 documentation/ 目录
  • 项目根目录中仅保留 README.md、LICENSE、.gitignore

MANIFEST 系统

节省 Token 的项目导航系统。完整文档见 manifest-system.md。

  • 会话启动时可减少 85-90% 的 Token 消耗
  • 根目录中的 MANIFEST.md 以约 1,500 个 Token 提供完整的项目概览
  • 为 data/、figures/、scripts/、documentation/ 子目录提供 MANIFEST
  • 每次会话结束时，使用 /update-manifest 更新

项目清理：识别必要文件

详细流程见 deprecation-guide.md（“项目清理”部分）。摘要：

  1. 分析笔记本，找出引用的图
  2. 将图映射到生成它们的脚本
  3. 将未使用的文件移至 deprecated/，并使用描述性子目录名称
  4. 在 MINIMAL_ESSENTIAL_FILES.md 中记录保留的内容
  5. 验证笔记本在清理后的结构中仍能正常工作

与其他技能集成

  • python-environment - 环境设置与管理
  • claude-collaboration - 团队工作流最佳实践
  • jupyter-notebook-analysis - 笔记本组织规范
  • data-backup - 备份系统应包含 MANIFEST
  • project-sharing - 在共享的软件包中包含 MANIFEST

快速设置

# Create standard research project structure
mkdir -p data/{raw,processed,external} notebooks scripts src tests docs results config
touch README.md .gitignore environment.yml

支持文件

文件内容
project-structures.md所有项目类型的详细目录模板
naming-conventions.md文件命名规则、模式和会话笔记存储方式
reorganization-guide.md分步重组、路径更新与验证
deprecation-guide.md弃用策略、整合和必要文件识别
documentation-organization.md文档规范、变更摘要和文档目录结构
manifest-system.md完整的 MANIFEST 系统：模板、命令、工作流和最佳实践

参考资料与资源

评论

支持 Markdown