APSer-Atelier 的几条原则

先说结论

• APSer-Atelier 背后的十四条原则，是我们在 AI 时代的项目开发与交付中，从一个个真实痛点里逐步沉淀下来的；本文介绍的是原则，不构成对产品功能的承诺。
• 第一组是经典的软件原则：深模块、只为真实场景增加复杂度、最小权限、规则集中把关、机制与策略分开、先想好怎么退。改动变快以后，这些老问题的分量反而更重了。
• 第二组回答 AI 的输出带有概率性这个新问题：上下文少而准，AI 起草、程序执行和把关，用评测衡量效果，工具可换、认知写在开放格式里，规矩写成钩子当场拦下。
• 第三组是工作方式：一件事实只认一个出处，一次一件事、一个仓一个写入者，「完成」分阶段拿证据，AI 自己报告「完成」不算证据。

APSer-Atelier 是青岛艾普仕在自身交付中使用的工作平台，目前仍在持续打磨中。它背后的原则，是我们在 AI 时代的项目开发与交付中，从一个个真实痛点里逐步沉淀下来的：碰到新问题、拿不准怎么做的时候，我们先回到这些原则对照。

下面十四条分成三组。第一组是经典的软件原则，有的来自软件设计著作，有的来自信息安全和管理领域的成熟做法；第二组是 AI 时代的原则，回答的是 AI 的输出带有概率性、会出错以后，系统该怎样搭；第三组是工作方式，回答一个人同时推进多个项目、大量借助 AI 执行时，工作该怎样组织。每条讲三件事：它说的是什么，我们为什么这样做，对交付意味着什么。

本文介绍的是我们遵循的原则，不构成对产品功能的承诺。

一、深模块：为什么接口要简单，复杂留在里面？

它说的是什么。 这个说法来自斯坦福大学 John Ousterhout 教授的《A Philosophy of Software Design》[1]：一个模块的内部实现明显比它对外的接口复杂，就称它「深」[2]。好的模块用很少、很简单的入口，把大量细节藏在内部。

我们为什么这样做。 AI 助手改代码很快，也容易顺着能调用的地方四处扩散：对外暴露的入口越多，被误用、被重复实现的机会就越多。把容易出错的细节收进一个入口很少的模块里，例如写文件时的编码、写到一半中断怎么办、哪些位置允许写，调用的一方就碰不到这些细节，也就改不坏。

对交付意味着什么。 容易出错的地方集中在少数几处，后续改动不容易牵一发而动全身；接手的人先看懂几个简单的入口，就能把握系统的大致结构。

二、为什么只为真实场景增加复杂度？

它说的是什么。 增加任何一层抽象之前，先回答「它服务哪个真实的使用场景」，答不出来就不加。已经稳定运行的部分，不为了好看而重写。

我们为什么这样做。 深模块有一个反面的诱惑：为想象中的将来提前搭框架。每多一层，以后每次修改都要多读一层、多验证一层。所以我们的取舍是：数据流转、权限、调度这类关键部分做深；界面展示这类部分保持简单，只做减法。

对交付意味着什么。 系统的结构跟着真实业务生长，您不必为想象中的需求买单；运行稳定的部分少动，减少无谓的风险。

三、为什么默认不给权限，需要什么再明确授予？

它说的是什么。 每个执行者，包括 AI 助手，起步时只有最少的权限：能读哪里、能写哪里、能运行哪些命令，逐项明确授予，并在边界处检查。这与信息安全领域的「最小权限原则」一致：只授予完成任务所需的最小权限 [3]。

我们为什么这样做。 AI 助手的输出不会每次都对，交给它的材料里也可能夹带误导性的指令。默认什么都能做，任何一次出错都可能造成破坏；默认什么都不能做，出错的影响就限定在授予的范围之内。

对交付意味着什么。 即使某一步出了错，波及范围也有边界；哪个执行器能动哪些东西，事先写得清楚，事后查得到。越权的写法，入口本身就不提供。

四、怎样集中把关规则，让错误不致命？

它说的是什么。 数据写入之前必须满足的条件，例如一项任务能从哪个状态变到哪个状态、引用的对象必须存在，集中写在一处；所有写入都先经过这里检查，不满足就拒绝。

我们为什么这样做。 同一条规则如果散在几处各写一遍，改了这一处、漏了那一处，就会出现这里拦、那里不拦，数据慢慢变得不一致。AI 助手一次往往只看到其中一处，更容易漏改。集中把关之外，我们还假定出错一定会发生：进程意外中断，重启时把停在半路的任务判为失败、回到一致的状态，不让它半死不活地挂着。

对交付意味着什么。 同一条规则改一处、处处生效；错误的数据在写入之前就被挡住，不必事后清理。

五、为什么要把机制与策略分开？

它说的是什么。 这是操作系统设计里的一条老原则：框架只管「怎么执行」，具体「做什么」由挂在框架上的一段段规则决定。新增一条规矩，是注册一段新的规则，不往主流程里加分支。

我们为什么这样做。 让 AI 助手改一条规矩时，改动如果要伸进调度主流程，就可能牵动所有任务。规则各自独立挂载，改一条只动一条，出了问题也只需撤下那一段。

对交付意味着什么。 新的要求能较快加进来，又不容易把已经稳定的部分改坏。

六、为什么动手之前先想好怎么退？

它说的是什么。 每次重要改动之前先问：如果改错了，从发现问题到完全恢复要多久？时间可以接受，就正常推进；时间太长，就先准备退路，例如新功能先用开关关着、验证通过再打开，关键上线前先备份。

我们为什么这样做。 AI 让改动变快，出错也会变快。亚马逊创始人贝索斯在 2015 年致股东信里把决策分为两类：难以回头的「单向门」要慎重，可以回头的「双向门」可以快速决定 [4]。我们借这个思路：能退回来的内部改动放手推进；风险大的动作在系统里直接设限，派出去的 AI 执行器不能推送、部署或改动凭据，涉及数据库迁移的改动不自动上线；涉及客户和对外承诺的事项，由人亲自处理。衡量的尺子是对业务的影响，改动的代码量说明不了什么。

对交付意味着什么。 出了问题，可以先把系统恢复到上一个验证过的版本，让业务照常运转，再查原因。

七、给 AI 的上下文，为什么要少而准？

它说的是什么。 大模型本身不记事，每次调用都要为它准备上下文。Anthropic 在 2025 年的一篇工程文章里把这件事称为「上下文工程」：要找的是信息量最高的那一小部分，给得越多并不越好 [6]。

我们为什么这样做。 塞给 AI 的东西越多，关键的几条越容易被淹没；过时的材料混进来，它会照着过时的做。所以每次开工，都从项目自己的权威文件现场取最新的一小部分：先读项目说明，再看当前状态，再看待办，其余按需再取。

对交付意味着什么。 AI 每次拿到的都是当下最新、最相关的信息，减少照着旧材料做错事的情况；换一个人或换一个工具接手，读的也是同一份材料。

八、为什么由 AI 起草，由程序执行和把关？

它说的是什么。 AI 的输出带有概率性，不会每次都对。所以让它做擅长的事：理解意图、起草、解释；真正改变数据和系统状态的动作，由行为确定的程序执行，AI 的输出要先通过格式和规则检查才会被采用。

我们为什么这样做。 把一段看似合理的 AI 输出直接当结论执行，出了错很难察觉。在它和执行之间设一道检查，错误就有机会在进入系统之前被拦下：AI 的输出按约定的格式解析，解析不过的归为失败，不反复重试碰运气。能用确定的检查判断的事，就不交给大模型。

经济学家阿格拉沃尔、甘斯和戈德法布在《权力与预测》里把 AI 归结为预测，并指出机器按事先写进去的判断行事，写进这些判断的人才是做决定的人 [7]。这条原则的分工与此一致：AI 负责预测，也就是起草和给出最可能对的结果；判断和拍板留给人，写成规矩和检查，由程序执行。在我们的交付里，这条分工由 APSer-Atelier 作为主控落实。这里说的 APSer-Atelier 主控包括两部分：面对我们的主控会话（一段 Claude Code 或 Codex 对话），负责组织和派出；Atelier 平台，负责登记每一件事、挂起待拍板、记下要求、按规矩放行并留下记录。

对交付意味着什么。 《排程为什么交给确定性求解内核，大模型只在外围工作》是这一条在生产排程上的具体做法：计划由求解器计算，写入前逐条核对约束，大模型负责解说，最后由人拍板。

九、怎样用评测衡量 AI 的效果？

它说的是什么。 普通代码的对错是确定的，同样的输入永远得到同样的输出；AI 参与判断的环节，对错是一个比例。衡量这类环节，要准备一组评测样例，定下基线，看通过率。

我们为什么这样做。 改一句提示词、换一个模型，通过率可能大幅变化，而且单看一两次结果发现不了。有了基线，每次改动后重跑一遍，退步了能看出来。

对交付意味着什么。 系统里用到 AI 的地方，改动前后有数可比，不靠「感觉好一些」下结论。

十、为什么工具可换，认知要写在开放格式里？

它说的是什么。 执行工作的 AI 编程工具可以替换，平台不绑定其中任何一家；项目的工程知识，包括架构决策、踩过的坑、实测结论，写在代码仓里多家工具都认的开放格式文档中，不只留在某一家工具的私有记忆里。能力也按「随时可能整段换掉」来设计：模型更新得比软件快，今天的做法过几个月可能就要重写。

我们为什么这样做。 我们换过一次主要的 AI 编程工具，也两家并用过。那段时间最深的教训是：认知锁在一家工具的私有记忆里，换工具就要从头重建，原来靠工具「记得」的规矩悄无声息地失效。

对交付意味着什么。 您的项目不绑定某一家 AI 工具；换了工具、换了人，项目知识照样在，能接着做。

十一、为什么把规矩写成钩子，当场拦下？

它说的是什么。 写下来的要求只能提醒，忙起来就会被跳过。能由机器判断的要求，我们写成钩子：在收到消息、调用工具、提交代码、推送代码、一轮回复结束这些固定时机，自动运行一段检查，按写好的条件放行或拦下。

我们为什么这样做。 同一条要求说过多次、写进了记忆和规则，照样一再被违反；拦截点放在出错的那一刻，才管得住。例如：会一次抹掉工作区里未提交改动的命令一律拦下，因为那些改动可能是别的会话正在写的；一个会话只能写开工时声明过的代码仓，范围外的写入、提交、推送都拦；推送即上线的代码仓，推送时必须写明是哪一个复核过的版本；推送之后没做验收，这一轮就不能结束；上线检查没跑完或报错，就不推送。设计钩子有三条讲究：判断看命令实际做了什么、写到哪里，不看它叫什么名字；检查脚本自己出错时默认放行，宁可漏拦也不卡住日常工作，只有上线检查反过来，出错就拦；判断不调用大模型，同样的输入每次得到同样的结论。钩子的来由和做法，见本栏目《从记忆、规则到钩子：让 AI 编程助手真正服从指挥》。

对交付意味着什么。 最常出错的那几类操作，由机器在当场拦下，不靠人盯、不靠 AI 记性；拦下了什么、为什么拦，都留有记录。

十二、为什么一件事实只认一个出处？

它说的是什么。 每一类事实只在一个地方说了算：项目的计划、进度和决策，写在项目自己的文档里；业务数据，留在业务系统里。Atelier 主要记工作进行到哪一步，以及指向这些出处的引用，一切以原出处为准；它能存哪些数据，列在一张明确的清单里，清单之外的一律不存。

我们为什么这样做。 同一件事抄在两处，迟早对不上，而且说不清该信哪一份。一条信息放在哪里，只看它属于谁：只属于一个项目的，放在那个项目里；天生横跨多个项目的，例如眼下正在推进哪几件事，才放进 Atelier。

对交付意味着什么。 您的系统和项目文档自成一体，不依赖我们这一侧的平台；两处说法对不上时，有明确的依据可查。

十三、为什么一次只做一件事，一个仓只有一个写入者？

它说的是什么。 安排工作的单位是一件完整的事：由一个明确的意图驱动，可能同时涉及几个项目；排期也按一整块来排，不切成一小步一小步地试。人的注意力同一时间只放在一件主要的事上。

我们为什么这样做。 按项目切，一件事会被撕成几片；同时开太多件，每件都在动，每件都推得慢。组织行为学者 Sophie Leroy 的研究发现，人从一项工作切到另一项时，前一项会留下「注意力残留」，影响后一项的表现，前一项没有收尾时尤其明显 [5]。所以离开一件事之前，我们先写下下一步，同时限制手上同时在做的事情数量。另一条限制在代码仓上：同一个代码仓同一时间只允许一个写入者，不同代码仓之间可以并行；复核只读，发现问题退回原来那一件事里改。

对交付意味着什么。 一件事从提出到验收由同一条线贯穿，来龙去脉集中在一处；您问起某项改动，能讲清前因后果。

十四、为什么「完成」要分阶段拿证据？

它说的是什么。 我们把「完成」拆成几段：改了代码、测试通过、提交、推送、上线、在真实环境里走通。每一段单独留证据，前一段的证据顶替不了后一段；AI 自己报告「完成」，不算证据。

我们为什么这样做。 「测试通过」「接口返回正常」「服务在线」都只证明了其中一段。用临时的小例子或「运行没有报错」代替在真实环境里看实际结果，是我们踩过最多次的坑。验收没通过，就在原来那件事里做一次有限的修正；还不行，就退回上一个验证过的版本，不另开一件新事绕过去。

对交付意味着什么。 我们说「交付完成」时，真实环境里的那一次验收一定做过，而且有记录可查。

以下是我们的看法

以下内容是我们的观点，供您参考。

第一组原则大多由来已久，AI 没有让它们过时。改动变快以后，接口是否简洁、权限是否收紧、规则是否集中、退路是否备好，这些老问题的分量反而更重了。

第二组原则回答的是一个新问题：AI 的输出带有概率性。我们的办法是把它装进确定的外壳里：给它少而准的上下文，让它起草、由程序把关，用评测看效果，用钩子在出错的时刻拦下。

第三组原则是给人用的。一个人同时推进多个项目，瓶颈是人的注意力，不是 AI 的速度。原则写下来的意义，在于换了工具、换了执行者，判断依据依然一致。

选择交付方时，您也可以请对方讲讲自己遵循哪些原则，以及每一条来自什么问题。能讲清来由的原则，更可能在日常交付里一直用着。

参考来源