diff --git a/docs/superpowers/specs/2026-06-23-project-structure-design.md b/docs/superpowers/specs/2026-06-23-project-structure-design.md
new file mode 100644
index 0000000..7bad345
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-23-project-structure-design.md
@@ -0,0 +1,61 @@
+# 项目结构设计
+
+**日期**: 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 即可）