claude-code-skills/docs/superpowers/specs/2026-06-23-project-structure-design.md

项目结构设计

日期: 2026-06-23 状态: 已确认

背景

claude-code-skills 是一个 Claude Code 技能集合仓库，托管在自建 Gitea（git.geyoyo.top/glj/claude-code-skills.git），为 Claude Code + DeepSeek v4 提供专业领域的能力扩展。

当前仓库仅有一个初始提交和 README.md，需要建立合理的项目结构来支持后续技能的管理。

设计目标

• 建立清晰、可扩展的项目结构
• 支持混合型技能（通用技能 + 领域技能）
• 遵循 YAGNI 原则，不过度设计

目录结构

claude-code-skills/
├── README.md              # 仓库介绍（已有，稍作更新）
├── CLAUDE.md              # 本仓库的 Claude Code 开发指南
├── .gitignore             # 忽略编辑器/系统文件
└── skills/
    ├── README.md          # 技能索引（列表 + 简介）
    └── <skill-name>/      # 每个技能一个目录（未来添加）
        └── SKILL.md

文件说明

.gitignore

忽略编辑器临时文件、系统文件等无需版本控制的内容。

CLAUDE.md

Claude Code 在本仓库中工作时的开发规范，包含：

• 技能目录命名约定（kebab-case，如 code-review、spring-boot）
• SKILL.md 编写规范（frontmatter 字段、结构要求）
• 提交信息格式（中文描述）
• 文档语言（简体中文）

skills/README.md

所有可用技能的索引，每个技能包含名称和一句话简介。新技能添加时同步更新此文件。

技能组织方式

采用扁平结构 — 所有技能直接放在 skills/ 下，不按领域分层。理由：

• 技能数量尚少，分层为时过早
• 技能天然跨域，硬分类会导致归属纠纷
• 与 README.md 已有约定一致

非目标

• 不创建技能模板目录（等有第一个技能后自然形成模板）
• 不创建 CONTRIBUTING.md（受众仅为仓库维护者自己）
• 不创建 CI/CD 配置（无构建/测试需求）
• 不创建 CHANGELOG（用 git log 即可）