让 AI 写出「三个月后还能看懂」的代码——一套可落地的提示词工程实践

你有没有遇到过这种情况：AI 帮你写了一段代码，跑通了，你提交了，三个月后回头看——完全不知道这段代码在干什么。

注释没有，变量名是 temp、data2、result_final，函数 150 行没有拆分，错误处理是一个空的 except: pass。

这不是 AI 的问题，是你给的 prompt 的问题。

---

问题的根源

大多数人让 AI 写代码的方式是这样的：

"帮我写一个解析 JSON 文件并上传到数据库的脚本"

AI 会给你一个能跑的脚本。但「能跑」和「可维护」之间，差了一套工程约定。

AI 本质上是在做「补全」——你给什么上下文，它就往那个方向走。你不说要注释，它就不写；你不说要类型标注，它就省略；你不说要拆函数，它就往一个函数里堆。

解决方案是：把你团队的代码规范直接写进 system prompt 或者 prompt 模板里，让 AI 每次输出都符合同一套标准。

---

实战：构建一个「可维护代码生成器」

下面这套代码用 Python 调用 Claude API，给它一个固定的代码风格 system prompt，然后接受用户的功能描述，输出符合规范的代码。

import os

from openai import OpenAI



# 用无量API，国内直连，比官方省60%

client = OpenAI(

    api_key=os.environ.get("WULIANG_API_KEY"),

    base_url="https://api2everything.xyz/v1"

)



CODE_STYLE_SYSTEM_PROMPT = """

你是一位资深后端工程师，帮用户写 Python 代码。



每次输出代码，必须严格遵守以下规范：



【命名规范】

- 变量名和函数名使用 snake_case，名称要表达意图，禁止 temp/data/result 这类无意义命名

- 类名使用 PascalCase

- 常量全大写加下划线



【函数规范】

- 单个函数不超过 30 行

- 每个函数只做一件事

- 所有函数必须有 Google 风格的 docstring，包含 Args 和 Returns



【类型标注】

- 所有函数参数和返回值必须有类型标注

- 复杂结构使用 TypedDict 或 dataclass



【错误处理】

- 禁止裸 except，必须捕获具体异常类型

- 异常信息要有上下文（用 f-string 拼接关键变量值）

- 关键操作加 logging，不用 print



【注释规范】

- 复杂逻辑必须有行内注释，解释「为什么」而不是「是什么」

- 文件顶部写模块说明和作者/日期



【结构规范】

- 超过 3 个参数考虑用 dataclass 封装

- 有副作用的操作（IO、网络、数据库）和纯计算逻辑分离



输出时先给出代码，再给一段不超过 5 行的「可维护性说明」，指出你做了哪些关键设计决策。

"""



def generate_maintainable_code(feature_description: str, language: str = "Python") -> str:

    """

    根据功能描述生成符合工程规范的代码。



    Args:

        feature_description: 用户描述的功能需求

        language: 目标编程语言，默认 Python



    Returns:

        包含代码和可维护性说明的字符串

    """

    user_prompt = f"""

请用 {language} 实现以下功能：



{feature_description}



按照你的代码规范输出完整实现。

"""



    response = client.chat.completions.create(

        model="claude-sonnet-4-5",

        messages=[

            {"role": "system", "content": CODE_STYLE_SYSTEM_PROMPT},

            {"role": "user", "content": user_prompt}

        ],

        temperature=0.2,  # 代码生成用低温度，减少随机性

        max_tokens=4096

    )



    return response.choices[0].message.content





def main():

    # 示例：让 AI 写一个 CSV 数据清洗脚本

    feature = """

    读取一个 CSV 文件，做以下清洗：

    1. 删除重复行

    2. 把 age 列的负数和超过 150 的值替换为 NaN

    3. email 列做格式校验，无效的打 warning 日志

    4. 输出清洗后的文件，文件名加 _cleaned 后缀

    """



    print("正在生成代码...\n")

    result = generate_maintainable_code(feature)

    print(result)





if __name__ == "__main__":

    main()

---

关键设计解析

为什么 temperature 设 0.2？

代码生成不需要创意，需要确定性。低温度让 AI 更倾向于选择「最规范」的写法，而不是「有趣但奇怪」的写法。

为什么要求「可维护性说明」？

这是一个强制 AI 自我审查的技巧。要求它说明设计决策，它在生成代码时就会更认真地考虑这些约束，而不是直接输出第一个能跑通的版本。

System prompt 和 user prompt 分离的好处？

System prompt 是你的「工程文化」，一次写好，所有请求都继承。User prompt 只描述具体功能。这样团队里每个人用同一份 system prompt，输出风格就会趋于一致。

---

进一步：把规范存成文件，团队共享

import json

from pathlib import Path



def load_style_guide(style_file: str = "code_style.json") -> str:

    """从配置文件加载代码规范，方便团队统一维护。"""

    style_path = Path(style_file)

    if not style_path.exists():

        raise FileNotFoundError(f"找不到风格配置文件: {style_file}")



    with style_path.open(encoding="utf-8") as f:

        style_config = json.load(f)



    # 把 JSON 配置拼成自然语言 prompt

    rules = "\n".join(f"- {rule}" for rule in style_config.get("rules", []))

    return f"代码规范（严格遵守）:\n{rules}"

把 code_style.json 提交到 git，所有人拉下来就能用同一套标准，规范变了改一处文件就行。

---

实际效果对比

同样的需求「写一个重试装饰器」，普通 prompt 和加了 system prompt 之后的输出，差异非常明显：

| 维度 | 无规范 prompt | 有规范 system prompt |

|------|--------------|---------------------|

| 函数命名 | retry | retry_on_exception |

| 类型标注 | 无 | 完整 |

| 错误处理 | except Exception | 捕获具体类型 |

| docstring | 无或一行 | Google 风格完整文档 |

| 日志 | print | logging.warning |

---

三个月后能看懂的代码，不是靠 AI 更聪明，是靠你给 AI 的上下文更清晰。把工程规范写进 prompt，AI 就成了你团队的编码标准执行者。

---

如果你想跑上面的代码，API Key 可以去 无量API 注册，支持 Claude / GPT / Gemini / DeepSeek 等 300+ 模型国内直连，比官方便宜 60%+，注册就送 ¥1 余额，改一行 base_url 就能用，不用折腾代理。

有问题欢迎评论区留言，或者点个赞让更多人看到这个思路。