0 引子 一次Java服务端的AI初体验
第一天，下载好了Agent客户端，配置好了api-key。AI说"准备好了"。第二天，我迎来了满屏红色。
一个简单需求，AI自信地交付了代码。然后：编译报错------它用了项目里没有的类 ；依赖冲突------它引入的包和现有版本打架 ；代码里全是魔法数字 和多层if-else ；更崩溃的是，它在Windows上生成了Linux路径和换行符，构建工具当场报错。
我修了一整天。第五天，我觉得AI不如手写。第八天，我回到了网页版。
问题出在哪？AI不笨，它只是不了解上下文------不知道依赖版本、不熟悉编码规范、不清楚操作系统差异。它像一个空降的天才，第一天就试图重构公司核心库。
我要为它补上这门"入职课"。这，就是我写这篇文章的原因。👌
1 AI需要什么？
假设AI是一位新入职的员工，它需要什么？
- 一台可接入公司办公网络的电脑（可以随便折腾的环境）
- 一个了解项目的同事（开发环境搭建、项目规则、代码规范）
- 一套舒适的开发工具（IDE、数据库管理软件、浏览器、办公套件）
是的，新员工需要的资源AI也同样需要。它可以描述为：
- 环境：一个沙箱环境（Linux或Unix系统）
- 上下文文档：一个包含项目描述、环境和代码结构、规则规范的文件（README.md）
- 工具：编译器、代码检索工具、数据库访问MCP、RedisClient
2 如何开始？
第一次启动时，在会话中输入如下指令即可：
阅读项目根目录的README.md，按要求初始化上下文文档，并自行安装JDK、Maven等环境，确保项目能本地运行。这里没有限定具体产品，因为他们的工作逻辑都差不多，背后模型的参数量足够，价格可以承受即可。
3 上下文文档如何管理？
如果说沙箱是AI的"身体"，那么上下文文档就是它的"大脑地图"。合理的文档结构能大幅减少AI的认知负担，让它快速定位信息、遵循规则、少犯错。
3.1 核心理念
让AI的"入职指南"像代码一样可读、可维护、可迁移。目标是：任何一个新接手的Agent，只要读懂了这套文档，就能立刻了解项目的全貌和规矩。
3.2 目录结构设计
对于多子项目的复杂项目，我采用了如下结构：
text
root\
README.md # 项目根描述：技术栈、目录结构、编译运行方式、通用编码规约
doc\ # 跨子项目的共享文档
subproject0\ # 子项目
README.md # 子项目描述：启动方式、测试方式、特有规约、技术债
doc\ # 子项目文档
需求1\ # 按需求归类
api\ # 接口文档
prd\ # 详细设计、需求拆分（可选）
test\ # 测试用例
resources\ # SQL脚本、配置变更
概要设计.md当一个需求涉及多个子项目时，就在上层的doc/目录下统一管理，避免文档散落。
3.3 设计原则
- 父子覆盖 ：子项目的
README.md继承根项目的通用规约，并可覆盖或补充特有规则。这样既保持了全局一致性，又允许子项目灵活自治。 - 简单明晰 ：所有
README.md都是纯文本，只陈述事实，不堆砌冗余信息。 - DRY原则：文档不重复。同一份信息（如接口定义）只存放在一处，其他地方通过引用或索引获取。
- 与代码同步 ：文档与项目代码一起提交。尤其是技术债、特例、偏离规范的实现，必须在
README.md中明确标注，避免文档"腐朽"。 - 内容闭环 ：文档中所有引用的文件（如设计文档、API定义、SQL脚本）必须使用项目内的相对文件路径，确保文档自成体系，不产生任何"外部依赖"或失效链接。
3.4 ⚠️ 关键提醒
绝对禁止在文档中放置任何生产环境的账号、密码、Token或密钥。 这些上下文文档会随代码库被Agent读取，也可能被多人共享。敏感信息应通过独立的密钥管理系统或环境变量注入，而非写在文档里。
4 工具的选型
好的工具可以提高工作效率，我遵循两个原则：
- 工具小而精：一个工具只干一件事，如专门的代码检索、专门的数据库查询。
- 让AI自己学 ：大部分CLI工具都支持
--help，AI可以自行查询用法，无需人工编写文档。
目前我们在沙箱中集成的工具包括：Python（用于快速脚本）、JDTLS（代码结构索引）、Chrome DevTools MCP（查阅在线文档）、SQL MCP Server（只读访问测试数据库）、curl（接口测试）。
这些工具不是固定的，会随着实践不断被替换或优化------只要达成"让AI高效地获取信息、执行命令"这个目的即可。
每种工具的详细配置方式，我会在后续系列文章中逐一拆解，本文只展示整体选型思路。
5 如何将其融入现有工作流程？
有了环境、文档和工具，最后一个问题也是最关键的问题：这套东西，怎么融入我每天真实的开发节奏里？
我的答案不是"全部交给AI"，而是建立一套**"AI产出，人工把关"**的协作闭环。下面是我在实践中跑通的6个步骤。
5.1 第一步：把需求"翻译"成文档
接手一个需求后，第一件事不是打开IDE，而是打开一个文本文件。
我把需求按项目结构整理成一个需求文档，描述背景、功能点、验收标准，然后保存到对应子项目的doc/需求名/目录下。这个动作很轻，但意义重大------它把产品经理模糊的口头需求，变成了AI能精确理解的结构化输入。
5.2 第二步：让AI输出"设计文档"
然后，我会开启一个会话，把需求文档路径"喂"给Agent，并提示它基于项目上下文（即我们维护的那份README.md）生成一份详细设计文档。
这一步的目标很明确：在写任何代码之前，先拿到一份可审查的方案。设计文档里应该包括接口设计、数据库变更、核心类设计等。
5.3 第三步：人工审查，就地纠偏
设计文档出来后，我会把它从头到尾过一遍。
如果设计跑偏了、方案选型不合适、或者需求本身就存在问题，我会直接在会话里和AI沟通，纠正方向，直到设计文档满足要求为止。所有的分歧和调整，都在"写代码之前"解决。
这是整个流程中最关键的一道关。设计对了，代码不会歪到哪里去。
5.4 第四步：开启新Agent，按图施工
上一步确认设计无误后，我会开启一个全新的Agent会话，把"确认版"的详细设计文档喂给它，让它按文档实现代码，自行编译和调试。
这里有个微妙的心理变化：我不会把原会话里的对话历史也带过去。新Agent带着设计文档重新审视代码，反而能发现一些历史对话中遗漏的细节。
5.5 第五步：让测试自动化"补位"
代码跑通后，我会把设计文档再喂给一个新Agent，让它生成自动化测试脚本或单元测试用例。
这一步的实际价值在于：AI生成的测试代码往往比开发代码更"规矩"，因为它严格按照设计文档来验证边界条件------而这些边界，人类开发者有时会偷懒忽略。
5.6 第六步：人工最终审查
最后，我会审查生成的业务逻辑代码和数据库表结构。如果发现问题，通过第三步的会话反馈给AI进行修复。确认无误后，整理会话记录，把本次沉淀的经验（如特定场景的提示词、好的设计思路）更新到项目的文档或Agent的Skill中。
在这套流程里，我的角色从"写代码的人"，变成了**"审查设计的人"和"验收结果的人"**。
6 沉淀和推广
一套方案如果只服务于一个人，价值就有限。真正的考验是：这套文档和流程，是否可读、可迁移、可复制？
6.1 哪些必须沉淀？
项目描述和目录结构、本地运行环境要求与启动调试方式、代码规约、技术债、非惯常的实现方案。这些是每一份README.md必须回答的问题，也是AI理解项目的基石。
6.2 哪些可以按需沉淀？
需求文档、API文档、测试用例、项目推荐使用的工具列表。这类内容随项目迭代自然积累，不必强求一步到位。
6.3 哪些不要沉淀？
与本地开发环境强相关的内容（如个人IDE配置），以及与个人偏好强相关的内容（如代码风格偏好）。文档里只写"约定"，不写"习惯"。习惯属于个人，约定属于团队。
6.4 如何推广到团队？
把README.md和doc/目录结构模板随代码库一起提交。团队其他成员只需拉取代码，按照相同结构初始化自己本地的Agent，就能获得一致的上下文。
这套方案的推广成本极低------因为它本质上就是一套文档规范 ，而不是一套新的工具链。只要团队愿意写几份README.md，AI就能完成剩下的大部分工作。
7 总结和展望
回到开头那个让我崩溃的场景------一个简单的需求，换来满屏的红色错误。
如果当时AI有一份完整的上下文文档，能在一个安全的沙箱里自由试错，能通过工具自主查询依赖版本和数据库结构，那一天的混乱，或许本可以避免。
Harness改造不是什么高深的理论。它只是一套**让AI"懂规矩、有工具、可试错"**的工程方法。它解决的不是AI"够不够聪明"的问题，而是AI"够不够了解你的项目"的问题。
本文只是一个开始。接下来的系列文章，我会逐一深入：
- 环境篇：如何用Docker构建一个让AI"随便折腾"的沙箱？
- 上下文篇 ：如何让
README.md真正成为AI的"入职指南"？ - 工具篇：如何通过MCP协议让AI自主查询数据库和代码结构？
- 流程篇：上述6步工作流中，每一步的提示词设计和踩坑记录。
如果你也在探索如何让AI融入Java服务端开发，欢迎关注后续更新，也欢迎在评论区聊聊你的实践。