什么是CLAUDE.md？claude-code-java如何为Java项目生成AI工作区配置

一、一分钟看懂 CLAUDE.md

📄CLAUDE.md是放在 Java 项目根目录下的一个 Markdown 文件，相当于AI 编程助手的工作区"说明书"。Claude Code 启动时会自动读取它，从而了解项目的技能清单、构建命令、测试策略和提交规范，让 AI 一上来就"懂行"，而不是每次都要你从零解释。

claude-code-java就是一个为 Java 项目量身打造的AI 开发基础设施：它提供 18 个可复用的 AI 技能（Skills）、项目模板和自动化脚本，其中最核心的一步，就是一条命令为你的 Java 项目生成 CLAUDE.md。

二、为什么 Java 项目需要 CLAUDE.md

没有 CLAUDE.md 时，AI 助手每个会话都是"失忆"状态，常见问题有：

💡 可以把它理解为：CLAUDE.md = AI 助手的员工手册，而 claude-code-java 是帮你批量打印这本手册的打印机。

三、claude-code-java 如何生成 CLAUDE.md

整个生成过程非常轻量，核心是"模板 + 占位符替换"，涉及三个文件：

1. 模板文件

templates/CLAUDE.md.template 是 CLAUDE.md 的"毛坯"，内含：

• 可用技能清单：git-commit、test-quality、issue-triage 等技能的使用示例
• MCP 服务器说明：GitHub、Filesystem、Git 三个 MCP 的能力与收益
• 常见工作流：日常开发、每周维护、代码评审的完整流程
• Token 预算指南：如何一次性加载技能、批量处理以节省开销
• 项目特定配置：构建命令、测试策略（JUnit 5 + AssertJ）、提交规范

其中{{PROJECT_NAME}}、{{REPO_NAME}}、{{DATE}}是占位符，等待脚本自动填充。

2. 生成脚本

scripts/generate-claude-md.sh 的工作分三步：

1. 探测项目名：取目标目录的目录名作为PROJECT_NAME
2. 探测仓库名：从git remote get-url origin解析出REPO_NAME（没有远程仓库时退回项目名）
3. 替换占位符：用sed把三个占位符替换为真实值，输出到项目根目录的CLAUDE.md

⚠️ 注意：如果你已手动写过 CLAUDE.md，脚本会直接覆盖它。建议先备份或重命名。

3. 一键编排脚本

scripts/setup-project.sh 把生成 CLAUDE.md 作为第 2 步，串联了完整的 4 步工作区配置：

四、三步在你自己的 Java 项目上启用

第 1 步：克隆 claude-code-java

git clone https://gitcode.com/gh_mirrors/cl/claude-code-java.git ~/projects/claude-code-java cd ~/projects/claude-code-java chmod +x scripts/*.sh

第 2 步：运行设置脚本，指向你的 Java 项目

./scripts/setup-project.sh ~/projects/your-java-project

执行完成后，你的项目里会出现：

your-java-project/ ├── CLAUDE.md # ✅ 自动生成的 AI 工作区配置 └── .claude/ ├── skills/ # 18 个软链接的 AI 技能 ├── settings.json # 预授权命令（mvn、git 等） └── ...

第 3 步：在项目里启动 Claude Code 开始使用

cd ~/projects/your-java-project claude

之后直接用自然语言触发技能即可，例如输入"commit these changes"会命中 git-commit 技能，"review this code"会命中 java-code-review 技能。也可以显式调用：

> /git-commit > /java-code-review

🔄 如果项目结构有变化（比如换了远程仓库名），重新跑一次generate-claude-md.sh即可刷新 CLAUDE.md。

五、进阶：只装技能、不要全套配置？

如果暂时只想体验技能、不想生成 CLAUDE.md，官方提供了更轻量的安装方式（无需克隆）：

npx skills@latest add decebals/claude-code-java

加上--list可以先预览全部技能，--skill <name>只安装指定的，--global装到用户级目录。需要 CLAUDE.md 生成、MCP 配置和权限设置时，再走上面的完整流程。

六、常见问题 FAQ

Q1：CLAUDE.md 必须提交到 Git 仓库吗？建议提交。它描述的是团队共享的 AI 协作规范，纳入版本管理能保证每位成员（和每位新加入的 AI 会话）拿到一致的工作区配置。

Q2：生成的 CLAUDE.md 可以手动修改吗？可以，而且推荐。脚本只负责初始化，模板末尾还留了"Project-Specific Notes"章节，你可以按团队实际情况补充构建命令、测试覆盖率目标、Issue 处理时限等细节。

Q3：settings.json 白名单里预置了哪些命令？默认放行 Maven（mvn *、./mvnw *）、Gradle（gradle *、./gradlew *）以及只读的 Git 查询命令（git status/log/diff/branch），详见 templates/settings.json.template。这正是"人始终在环上"（Human-in-the-loop）安全原则的落地，见 docs/DESIGN_PRINCIPLES.md。

七、总结

🚀 想让 AI 在 Java 项目里"开箱即用"？跑一次setup-project.sh，让 CLAUDE.md 替你完成所有的"入职介绍"。

更多脚本选项参见 docs/SCRIPTS.md，技能完整文档见 skills/README.md，项目总览见 README.md。