ARTICLE · 1293201

怎么用 SDFrame?一本软件设计手册,与一份 AI 编程防乱指南

发布时间：2026-11-01 22:44:36 最近访问：2026-11-01 22:44:36

怎么用 SDFrame？一本软件设计手册，与一份 AI 编程防乱指南

让 AI 写一个小工具或者业务脚本，最爽的是前五分钟：把需求往对话框里一丢，代码瞬间吐出，终端里敲个回车就跑通了。

最容易让人心烦的是第二天。

你想给刚才做好的记账脚本加个小功能：原本只打印纯数字，现在想让金额前面带上 ¥ 符号。你跟 AI 说“金额前面加个人民币符号”，AI 很快改完。终端刷新了一下，符号确实出来了，紧接着你发现余额算错了——本来还有 70 块，现在要么变成了 0，要么直接抛出类型错误崩溃。

打开代码一看，AI 并没有只改排版，它顺手把算账的那行改成了带符号的字符串。

这时很多人会去问 AI：“代码太乱了，该怎么改？”

AI 大概率会立刻开启“大厂架构师模式”，甩出一堆大词：“建议引入分层架构”“采用关注点分离原则”“使用领域驱动设计”。这些词听着都对，但面对几十行的小脚本，你根本不知道该信哪一个，更不知道该怎么动手。

这时候，最适合打开 SDFrame^[1] 翻一翻。

它是一本软件设计方法的查病手册

先说清楚它是什么。

SDFrame 不是 Vue、React 或 FastAPI 这类可以通过 pip install 或 npm install 装进项目的软件运行库。它本质上是一份软件工程与设计方法的速查手册。

这里的 Framework，指的是面对特定的软件麻烦时，前人踩过无数次坑总结出来的套路。有的讲怎么切分代码，有的讲测试怎么分层，有的讲架构决策怎么记录。

它收录这些内容，不是为了让人背概念，而是为了让人在被代码卡住、被 AI 绕晕时，能当场查到对症的药方。

比如上面遇到的记账问题：为什么改个排版，会把算账搞崩？

拿这个问题去翻 SDFrame，最直接对应的是 Separation of Concerns（关注点分离）^[2]。英文名不用死记，它在工程上其实就一句话：不同的职责各管各的事，不要混在一块。

第一步：现场还原，一页资料只抓两头

很多用 AI 随手写出来的小程序，最开始都长这样：

def show_balance(income, expense):    # 算账和排版直接挤在一块    balance = income - expense    return f"¥{balance:.2f}"

只有两三行时，谁都会觉得这样写最省事。但只要功能再往后走一步，麻烦就来了：如果你接下来想判断“余额是否小于 0”，或者想拿两个账户的余额做累加，调用 show_balance 拿回来的却是一串文本 "¥70.00"。

再让 AI 去修，AI 很可能会在后面又写一行字符串切片，先把 ¥ 剔掉再转成 float 去算。改动越滚越大，整段逻辑很快就会烂成一团泥。这就是代码腐化的典型起点：修改排版的需求，被迫穿过了负责算账的代码。

打开 SDFrame 的条目，里面会有背景、复杂度、实施步骤等很多字段。刚上手时不用从头读到尾，盯住两处就够了：

1.第一处看 When to Use（什么时候适合用）：条目里明确写着：当 UI 排版变化频繁，或者业务规则需要独立测试时，适合拆开。对照记账软件的现状：货币符号属于排版，收支相减属于算账，排版天天想变，算账规则却不能动。这说明方法对症了。

2.第二处看 When NOT to Use（什么时候千万别用）：条目里写得清清楚楚：生命周期极短的原型、或者几行就能搞定的临时小脚本，不要强行硬拆。

这一处就是专门用来防过度设计的刹车片。很多新手查到了设计模式，转头就让 AI 给 20 行脚本建 5 个文件夹、写 3 层抽象接口，纯属自己给自己找罪受。

第二步：拆代码的第一刀，拆到哪里就该收手

读完条目，不要一上来就搞全盘重构。拆代码的第一刀极其朴素：先把“负责算账的纯函数”从“负责排版和打印的代码”里摘出来。

def calculate_balance(income: float, expense: float) -> float:    # 纯计算：只拿数字算数字，绝不碰任何字符串格式    return income - expensedef format_balance(balance: float) -> str:    # 纯排版：只拿算好的数字拼显示，不管数字怎么来的    return f"¥{balance:.2f}"balance = calculate_balance(100, 30)print(format_balance(balance))

立下规矩后：

calculate_balance
绝不碰引号，绝不返回带 ¥ 的文本；
format_balance
绝不做减法，绝不重新计算金额。

分工明确之后，下一次你想把金额改成 70.00 元，直接指着 format_balance 改。负责算账的代码一动不动，余额绝不可能被改错。

那么，拆到什么时候必须停？

当每一次修改都能精准定位到一个函数，并且改它不会波及旁边的逻辑时，立刻停手。

几十行的小脚本，拆出两个职责明确的函数就足够了。只有当保存账单从“写本地文本”变成“对接数据库和远程同步”，或者团队有多个人每天在同一份文件里改冲突时，才需要考虑分目录、分模块。坚决不为还没发生的事情提前造架构。

第三步：答案写在前面，用断言把底线锁死

改完了代码，最让人心虚的时刻，就是 AI 微笑着打出一句：“代码已按您的要求优化完毕，运行一切正常！”

这时候千万别急着信。

很多人所谓的验收，就是顺手在浏览器里刷新一下，看到页面能弹出来、没有报错红字，就觉得真改好了。这种凭感觉验收，只能证明没有语法错误；至于金额到底算对没有、边界情况有没有漏算，看一眼界面根本看不出来。

要想知道 AI 有没有改对，手里必须事先捏着一套死数据：

输入（收入, 支出）	预期余额	检查重点
100, 30	70	正常收支计算
0, 30	-30	零收入透支（负余额支持）
100, 0	100	零支出
0, 0	0	全零边界

把这几道题直接写成 Python 的 assert（断言），让电脑替你一秒跑完：

def calculate_balance(income: float, expense: float) -> float:    return income - expense# 跑四道死题目assert calculate_balance(100, 30) == 70assert calculate_balance(0, 30) == -30assert calculate_balance(100, 0) == 100assert calculate_balance(0, 0) == 0print("四项核心计算检查通过")

assert 的逻辑极其粗暴：算式成立，程序静默通过；一旦算错，当场砸出 AssertionError 中止。

在 SDFrame 里，这对应 Test Pyramid（测试金字塔）^[3]。不用背什么复杂层级比例，工程上记住两层就够了：

底层的快检查（单元测试）
：像 calculate_balance，0.001 秒跑完，核心算法、金额计算、边界转换统统放在这一层，写几十个也不心疼；
顶层的接通检查（端到端/集成检查）
：真实录入一笔支出，点击保存，关闭程序重新打开，确认文件里确实有这一笔，保证整条链路能接通。

两头兼顾，既不凭感觉瞎点，也不给简单逻辑写一堆臃肿的模拟测试。

第四步：给 AI 戴上紧箍咒，把手册当约束而不是扩建令

不少人知道 SDFrame 是个好东西之后，兴奋地把链接甩给 AI：“参考 SDFrame 里的优秀设计方法，帮我把记账软件重构一下。”

接着灾难就发生了：AI 会瞬间化身为大厂架构师，把几十行脚本拆成十几个文件，凭空造出抽象工厂、观察者和多层依赖注入。改一个变量名要跳五个文件，整个小工具彻底失去了原本的灵巧。

AI 缺乏现实成本感知，生成 500 行模板代码对它只要两秒钟，但后续维护全得由你兜底。

要让 AI 参考方法又不乱套，核心原则是：带着具体问题查，强制检查禁忌项，锁死改动红线。

一段合格的任务指令应当像这样写：

任务：解决记账软件中“修改金额排版容易碰坏余额计算”的问题。参考资料：阅读 SDFrame 关注点分离条目：https://sdframe.caldis.me/frameworks/separation-of-concerns执行规则：1. 重点阅读条目中的 When NOT to Use。当前项目仅有几十行代码，禁止做过度设计。2. 保持单文件结构，仅将紧密耦合的计算与显示拆为两个独立函数。3. 严格保留现有的金额单位、收支规则与数据保存方式，不引入任何第三方依赖。交付与验收：- 指出原代码混淆的具体行号，并给出重构后的完整 diff。- 保证已有的 4 项核心余额检查通过，且新增的排版“¥70.00”输出正确。

当有了这套约束，AI 就会明白你的意图是“治病”，而不是“扩建”。它会老老实实地在当前文件里做最小精度的手术。

怎么判断 AI 有没有听懂人话？

不及格的空泛回答
：“建议将系统进行分层重构，构建 Domain 领域模型层处理业务逻辑，引入 Service 层协调事务……”（全是套话，根本不敢落到行号）
合格的工程回答
：“app.py 第 14 行到第 19 行在计算余额的同时把文本赋给了 balance 变量，导致第 32 行汇总报错。我将这 6 行拆为 calculate_balance 和 format_balance。单文件保持不变，diff 和测试输出如下……”

至于 SDFrame 官方提供的 Skill 和自动化读取接口，在肉眼查熟之前，先别急着接。 如果自己连代码为什么该拆都想不明白，自动给 AI 挂上检索库，它只会更高效地生产出你看不懂的复杂垃圾。