作为移动端开发，我天天盯着那点 API 调用成本和接入效率，说实话，这种“去文档化”的想法挺危险的。代码和 Spec 只能告诉你系统“怎么跑”，但它们永远解释不了“为什么这么跑”。

Agent 确实牛，模式匹配和语法执行没得说，但它理解不了架构设计的权衡（Trade-off），更读不懂那些为了兼容老版本留下的“坑”。如果只给机器喂原始代码，它只会机械地执行，一旦遇到边界条件，出来的全是“逻辑垃圾”。

我之前试过让 LLM 自动生成文档，结果发现如果不加干预，它会陷入一种“用幻觉描述幻觉”的死循环——生成的文档看似专业，实则全是废话。要解决这个问题，不能完全甩手给 AI，得用一种“动态生成+人工审计”的思路。

我总结了一个专门用来辅助梳理设计意图（Design Intent）的 Prompt，不是让它单纯翻译代码，而是逼它去思考背后的逻辑。你可以把它集成到你的 CI/CD 或者代码评审流程里，别让文档变成一堆没用的 Slop。

# Role: Senior Software Architect & Intent Analyzer
Context: 

You are reviewing a code change. The goal is not to describe what the code does (the code already says that), but to capture the intent, rationale, and architectural constraints.
Task:

Analyze the provided code diff and the surrounding context. Generate a "Design Rationale" entry for our internal documentation.
Output Format (Strict):

💡 Intent & Rationale

Why this change? (Explain the business logic or technical debt being addressed)

Decision Trade-offs: (Why this approach instead of alternatives? Mention performance vs. readability vs. scalability)
⚠️ Edge Cases & Constraints

Hidden Gotchas: (Any specific historical context or legacy edge cases this code interacts with?)

Agent Guardrails: (Crucial instructions for any AI agent or developer interacting with this module)
Input Data:

[Insert Git Diff or Function Context Here]

说到底，现在的瓶颈不在于 AI 生成能力不够，而在于我们缺乏一套衡量知识库“可信度”的标准。在大家还在为 AI 生成的内容是否靠谱而纠结时，守住那点 Markdown 文件的底线，让机器也能读懂“弦外之音”，才是最务实的做法。