让 AI 写出「三个月后还能看懂」的代码：一套可落地的 Prompt 工程方案
让 AI 写出「三个月后还能看懂」的代码：一套可落地的 Prompt 工程方案
很多人用 AI 写代码的方式是这样的：
"帮我写一个处理用户登录的函数"
然后拿到一段能跑的代码，粘贴进去，提交，完事。
三个月后，你盯着那段代码，完全不知道它在干什么。没有注释，变量名是 temp、data、result，函数 80 行没有分段，没有任何错误处理的解释。
这不是 AI 的问题，是你问的方式不对。
问题的根源：AI 默认优化「可运行」，不优化「可维护」
AI 模型的训练目标是生成符合预期的输出。你说"写个函数"，它就给你一个能跑的函数。它不知道你三个月后还要回来改这段代码，也不知道你的同事英语不好、注释要写中文。
你需要在 Prompt 里显式声明"可维护性"需求。
下面给一套完整的方案，包括 Prompt 模板和自动化脚本。
核心 Prompt 模板
把以下模板保存成你的代码生成 system prompt：
你是一名高级工程师，代码风格遵循以下原则：
1. 每个函数必须有 docstring，说明：功能、参数类型、返回值、可能抛出的异常
2. 复杂逻辑前加行内注释，解释「为什么这样做」而不是「做了什么」
3. 变量命名用完整英文单词，禁止 temp/data/result 这类无意义名称
4. 单个函数不超过 40 行，超过则拆分
5. 所有异常必须被捕获并记录，不允许空 except
6. 在文件顶部写一段 2-3 句话的模块说明，说明这个文件的职责边界
生成代码后，额外输出一个「维护指南」块，说明：
- 这段代码依赖哪些外部状态
- 未来最可能需要修改的地方
- 已知的局限性
实战：用 Python 封装一个「可维护代码生成器」
下面是一个完整可运行的脚本，调用 OpenAI 兼容接口，自动生成带维护说明的代码：
"""
maintainable_codegen.py
职责：接收自然语言需求，生成带完整注释和维护指南的 Python 代码。
依赖 OpenAI 兼容 API，可通过修改 base_url 切换不同服务商。
"""
from openai import OpenAI
# 使用无量Api，国内直连，无需代理
client = OpenAI(
api_key="your_api_key_here",
base_url="https://api2everything.xyz/v1"
)
SYSTEM_PROMPT = """
你是一名高级 Python 工程师，代码风格严格遵循以下规范：
1. 每个函数/类必须有 Google 风格 docstring（功能、Args、Returns、Raises）
2. 复杂逻辑的行内注释解释「为什么」，不解释「是什么」
3. 变量名使用完整描述性英文，禁止 temp / data / res / val 等
4. 单函数不超过 40 行，超出则拆分为私有辅助函数
5. 所有 except 块必须记录异常信息，不允许 silent fail
6. 文件顶部三引号说明：模块职责 + 主要使用场景
代码生成完毕后，追加一个 Markdown 格式的「## 维护指南」，包含：
- **外部依赖**：依赖的环境变量、数据库状态、第三方服务
- **易变点**：未来最可能需要改动的逻辑位置和原因
- **已知局限**：当前实现的边界条件和不适用场景
"""
def generate_maintainable_code(requirement: str, model: str = "gpt-4.1") -> str:
"""
根据自然语言需求生成带维护说明的 Python 代码。
Args:
requirement: 自然语言描述的功能需求
model: 使用的模型名称，默认 gpt-4.1
Returns:
包含代码正文和维护指南的字符串
Raises:
openai.APIError: API 调用失败时抛出
"""
response = client.chat.completions.create(
model=model,
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"需求：{requirement}"}
],
temperature=0.2 # 低温度，减少随机性，提高代码一致性
)
return response.choices[0].message.content
def save_generated_code(requirement: str, output_path: str) -> None:
"""
生成代码并保存到指定文件路径。
Args:
requirement: 功能需求描述
output_path: 输出文件的绝对或相对路径
Raises:
IOError: 文件写入失败时抛出
openai.APIError: API 调用失败时抛出
"""
print(f"正在生成代码，需求：{requirement[:50]}...")
generated_content = generate_maintainable_code(requirement)
with open(output_path, "w", encoding="utf-8") as output_file:
output_file.write(generated_content)
print(f"已保存至：{output_path}")
if __name__ == "__main__":
example_requirement = """
实现一个速率限制装饰器，支持：
- 按调用次数限制（每分钟最多 N 次）
- 超出限制时等待而不是直接报错
- 线程安全
"""
save_generated_code(example_requirement, "rate_limiter.py")
进阶：让 AI 审查已有代码的可维护性
已有老代码，想知道三个月后还能不能看懂？加一个审查函数：
def review_maintainability(code_snippet: str) -> str:
"""
审查代码的可维护性，返回具体的改进建议。
Args:
code_snippet: 待审查的代码字符串
Returns:
包含评分和逐条改进建议的 Markdown 字符串
"""
review_prompt = """
请从「三个月后的陌生人」视角审查以下代码的可维护性，输出：
1. **可维护性评分**（1-10）及一句话理由
2. **具体问题清单**：每条指出行号和问题类型
3. **重构优先级**：按影响从高到低排列需要修改的地方
4. **改写示例**：选最严重的一个问题，给出改写前后对比
代码如下：
"""
response = client.chat.completions.create(
model="gpt-4.1",
messages=[
{"role": "user", "content": f"{review_prompt}\n\n```python\n{code_snippet}\n```"}
],
temperature=0.1
)
return response.choices[0].message.content
几个实测有效的小技巧
1. 在需求里加时间维度
不要说"写一个缓存函数"，说"写一个六个月后不需要我解释就能被新同事修改的缓存函数"。这句话会触发模型生成更多上下文说明。
2. 让模型扮演「未来的读者」
在 prompt 末尾加一句："生成完毕后，用一个不了解这段代码的工程师的视角，指出最难理解的三行"。
3. 温度调低
代码生成任务把 temperature 设在 0.1-0.3，减少创意发挥，提升命名和结构的一致性。
关于 API 费用
上面的脚本用了 gpt-4.1，官方调用成本不低。如果你每天要生成或审查大量代码，建议用 无量Api 作为转发层——支持 300+ 模型，国内直连不需要代理，价格比官方便宜约 65%。改一行 base_url 就能切换，上面的代码已经写好了。注册还送 ¥1 余额，余额永久有效，可以先试试效果。
如果你在自己的项目里用了类似的方案，或者遇到 AI 生成代码可维护性的其他问题，欢迎评论区聊。觉得有用的话点个赞，后续还会出更多 Prompt 工程的实战内容。