用 AI 写项目 README 与技术介绍：让代码和项目自己会说话
别让 AI 凭空编，先把仓库给它看
写 README 的头号坑，就是让模型凭项目名瞎编一通，写出来跟实际代码对不上，接手的人照着跑全报错。正确做法：把仓库结构、关键文件、入口函数这些真实信息喂给它，让它基于事实写。我带新人交接时最怕这种"文档与代码两张皮"的活儿，坑死后来人。AI 现在能读你贴的代码和目录，原料给足，它写的才靠谱。别偷懒只给个名字，那跟让瞎子画地图没两样。实打实把仓库亮出来，它才写得准。
结构照着标准 README 来
README 有套路，别整花活。让 AI 按固定骨架填：项目是干啥的、怎么装、怎么跑、大概结构、常见问题。这跟写接口文档一个理儿，结构稳了谁都看得懂。我见过太多人 README 写得像抒情散文，新人看了半天不知咋启动。你给模型下指令"按标准开源 README 结构来，别加废话"，它立马规矩。骨架固定，内容填准，这文档就合格了大半。花哨救不了说不清，老炮都走标准件。
把"怎么跑起来"写到人能复现
README 里最金贵的是"怎么跑"。环境、依赖、那条启动命令，一步都不能含糊。让 AI 把步骤拆到"复制这条、执行那条"，别写"自行配置环境"这种废话。我交接项目被坑最惨的一次，就是上家写了句"环境见配置"，配置里又没写版本，折腾一下午。你让模型基于你的真实依赖文件写，写出来的命令才真能跑。可复现，是 README 的及格线，跑不起来等于没写，还添乱。
设计取舍要说清，别只说结果
光写"用了 Redis 做缓存"不够，得说"为啥用、踩过啥坑、后来咋调的"。后来人看的是你的思考，不是结论。让 AI 帮你把关键决策背后的权衡写出来，比如"当初图快用了方案 A，后来量上来发现瓶颈，换成 B"。这跟写代码注释要写"为什么"一个道理。我读别人项目，最感激这种交代。模型初稿常只给结果，你专门让它补"当时咋想的"，文档才有灵魂。只给结论的文档，后人不敢改，也不敢信。
技术介绍和 README 是两码事
README 是给用的人看的，技术介绍是给想了解架构的人看的，别混。技术介绍多讲设计图、模块关系、扩展性，少讲怎么装。让 AI 分别产出两版，别一股脑塞一起。我汇报时吃过亏，把安装步骤堆进架构介绍，听的人一头雾水。分清楚 audience，文档才各司其职。这层分寸，老手都懂，新手容易糊。两版分开，谁看哪份都顺，你汇报也省口水。
老程序员的回炉习惯
最后一条，README 不是写完就完，代码一改文档就得跟。我习惯每次大改动后让 AI 比对下新代码和旧文档，把对不上的地方标出来重填。文档腐化是常态，不维护俩月就成摆设。工具帮你把"写"这步变轻松，但"常更"这习惯得你自己养。代码会说话，前提是有人替它把话说清楚。整明白了，交接、开源、汇报全省心，再没人追着你问"这项目咋跑"。我见过因为文档烂，好项目被人当半成品接手最后荒掉的，真心可惜。
