claude-md

MizzenAI 所有项目的 CLAUDE.md 集中管理仓库。

为什么需要这个仓库？

Claude Code 通过项目根目录和子目录中的 CLAUDE.md 文件来了解项目的架构、规范和约定。随着团队项目增多，这些文件散落在各个仓库中，带来几个问题：

• 同步困难：多台开发机器、多个部署环境之间的 CLAUDE.md 容易不一致
• 版本失控：修改后难以追踪变更历史和 review
• 协作低效：团队成员各自维护，知识无法统一

本仓库将所有 CLAUDE.md 集中管理，通过 symlink（软链接） 映射回各项目目录，实现单一信息源。

工作原理

claude-md/                              personality_workspace/
├── mizzen-insight/                     ├── CLAUDE.md → claude-md/mizzen-insight/CLAUDE.md
│   ├── CLAUDE.md                       ├── ai-user-interview-frontend-website/
│   ├── frontend-website/               │   └── CLAUDE.md → claude-md/mizzen-insight/frontend-website/CLAUDE.md
│   │   └── CLAUDE.md                   ├── ai-user-interview-backend-api/
│   ├── backend-api/                    │   └── CLAUDE.md → claude-md/mizzen-insight/backend-api/CLAUDE.md
│   │   └── CLAUDE.md                   └── Personality/
│   ├── backend-agent/                      └── CLAUDE.md → claude-md/mizzen-insight/backend-agent/CLAUDE.md
│   │   └── CLAUDE.md
│   └── init.sh                         # ← 运行这个脚本自动创建所有软链接
└── README.md

Claude Code 的加载机制：当你在某个目录下使用 Claude Code 时，它会自动加载该目录及所有父级目录的 CLAUDE.md。例如在 frontend-website/src/ 下工作，会同时加载根目录和 frontend-website/ 的 CLAUDE.md，但不会加载 backend-api/ 的——按需加载，不浪费 token。

快速开始

1. Clone 到 workspace 目录下

cd ~/WorkSpace/personality_workspace  # 你的项目 workspace
git clone https://github.com/MizzenAI/claude-md.git

确保目录结构如下：

personality_workspace/
├── claude-md/                              # 本仓库
├── ai-user-interview-frontend-website/     # 前端
├── ai-user-interview-backend-api/          # 后端 API
├── Personality/                            # Agent
└── ...

2. 运行 init 脚本

cd claude-md/mizzen-insight
./init.sh

脚本会自动：

• 检测 workspace 路径（支持子目录和同级目录两种布局）
• 为每个 CLAUDE.md 创建相对路径的软链接
• 如果已有软链接且指向正确，跳过（幂等）
• 如果已有普通文件，备份为 .bak 后再创建链接

也可以手动指定项目路径：

./init.sh /path/to/personality_workspace

3. 验证

ls -la ~/WorkSpace/personality_workspace/CLAUDE.md
# 输出: CLAUDE.md -> claude-md/mizzen-insight/CLAUDE.md

日常使用

编辑 CLAUDE.md

直接编辑项目目录中的 CLAUDE.md 即可（它是软链接，修改会写入本仓库）：

# 在项目中正常编辑
vim ~/WorkSpace/personality_workspace/ai-user-interview-frontend-website/CLAUDE.md

提交变更

cd ~/WorkSpace/personality_workspace/claude-md
git add -A
git commit -m "Update frontend-website CLAUDE.md"
git push

其他机器同步

cd ~/WorkSpace/personality_workspace/claude-md
git pull

由于使用了软链接，pull 后所有项目目录立即生效，无需额外操作。

目录名映射

由于 workspace 中的子项目目录名与本仓库中的目录名不同，映射关系如下：

本仓库目录	Workspace 目录	说明
mizzen-insight/CLAUDE.md	./CLAUDE.md	Workspace 根目录
mizzen-insight/frontend-website/	ai-user-interview-frontend-website/	Next.js 前端
mizzen-insight/backend-api/	ai-user-interview-backend-api/	FastAPI 后端
mizzen-insight/backend-agent/	Personality/	Python Agent Workers

添加新项目

1. 在本仓库中创建项目目录，放入 CLAUDE.md 文件
2. 在 init.sh 的 LINKS 数组中添加映射关系

LINKS=(
  ".:CLAUDE.md"
  "ai-user-interview-frontend-website:frontend-website/CLAUDE.md"
  "ai-user-interview-backend-api:backend-api/CLAUDE.md"
  "Personality:backend-agent/CLAUDE.md"
  "new-project:new-project/CLAUDE.md"  # 新增
)

注意事项

• 不要在项目仓库中 commit 软链接：如果项目仓库的 .gitignore 没有忽略 CLAUDE.md，git 会把软链接作为文本文件提交（内容是目标路径）。建议在项目的 .gitignore 中添加 CLAUDE.md
• 路径约定：init.sh 支持 claude-md 作为 workspace 的子目录或同级目录两种布局
• 备份机制：如果目标位置已有普通文件（非软链接），脚本会自动备份为 CLAUDE.md.bak.<timestamp>