pstack 基础思维Foundational Thinking在写任何逻辑之前先把数据结构定对【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins本文解读 Cursor 插件 pstack 内置的二十三条工程原则之一——Foundational Thinking基础思维。它规定了一个被绝大多数 AI 编码工作流跳过的最关键步骤在写逻辑之前先选定核心类型与数据结构、排定脚手架与功能的先后顺序、问清楚并发参与者之间共享什么。读完本文你将掌握这套先定结构、再写代码的可操作方法并理解它如何与 pstack 的类型系统纪律、领域建模、架构设计等原则协同让下游代码顺理成章。从原则到结构Foundational Thinking 在 pstack 中的定位pstack 是作者 poteto 公开的一套个人工程技能集核心主张是想要快先深入go deep first目标是写出更少但质量更高的代码。它通过/poteto-mode在任务开始时读取全部二十三条原则的索引按任务触发相应原则并在回复中点名哪条原则改变了哪个决策。在 pstack 的原则总表 中Foundational Thinking 属于core核心分组与 Laziness Protocol、Redesign from First Principles、Attack the Premise、Subtract Before You Add 并列是最先被应用的一组原则。它的触发时机写在其技能文件 frontmatter 的 description 中Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.即在写逻辑之前——选择核心类型与数据结构、安排脚手架与功能的先后、询问并发参与者共享什么。把数据结构弄对下游代码就变得显而易见。poteto-mode 的原则索引 将该原则的适用场景浓缩为一句写逻辑之前核心类型与数据结构、脚手架与功能的排序、并发参与者共享什么。而 原则使用指南 特别强调原则不是用来调用的而是用来指名道姓地引导steer with principle names——当 agent 准备把新适配器硬接进三个已有适配器时一句use subtract before you add比一段长指令更精准。第一性二分结构决策守护选项价值代码决策守护简洁原则开篇给出了全篇的纲Structural decisionsprotect option value.Code-level decisionsprotect simplicity.结构性决策Structural decisions核心类型、数据结构、模块边界、调用关系。这类决策一旦做错改动成本呈指数增长因为它会渗透到每一个调用方。因此它们守护的是选项价值option value——未来还能低成本改动的余地。代码级决策Code-level decisions单个函数内部的实现细节。这类决策错了代价小、好修正因此应该以简洁为最高准则不必过度设计。这一二分法解释了整条原则的布局把最多的思考精力花在数据结构上结构性决策把代码级决策交给显式优于巧妙测试行为而非行数这些低成本规则。数据结构优先先定形状再写逻辑原则的正文第一条规则Data structures first.Get the data shape right before writing logic. Define core types early, trace every access pattern, and choose structures that match the dominant paths.三步走尽早定义核心类型Define core types early追踪每一种访问模式trace every access pattern——谁读这个字段、谁写它、以什么频率、什么路径访问选择与主导路径匹配的结构choose structures that match the dominant paths——优化最常走的路径而不是为所有路径的平均值设计。这一思想在 pstack 的工作流中无处不在Feature playbook 在委托子代理写代码时要求先指定命名的数据形状及其组织结构named data shape and its organizing structure、状态机取代散布的布尔值、表/注册表取代分支、类型化模型取代重复的形状假设并且这一切必须在委托方写任何逻辑之前选好。poteto-mode 的触发规则 规定任何代码 → 先说出数据形状并按 principle-model-the-domain 选择其组织结构。architect 技能 把设计优先于实现制度化为五个阶段Ground → Sketch → Agree → Implement → Scrap用未实现的函数体和伪代码先画出类型、签名与模块边界再让多个模型并行产出设计草图经 arena合成后再填充实现。与 Type System Discipline 结合数据形状的选择会进一步收紧用和类型sum type让非法状态不可表示用 branded primitive 区分语义不同的同底层类型从权威 schema 派生类型。这两条原则一前一后Foundational Thinking 决定形状是什么Type System Discipline 决定如何把这个形状建模得让编译器替你守住边界。判断数据形状是否正确的提问原文档虽未给出逐条 checklist但从其trace every access pattern的要求可以提炼出落地时的自检问题这个类型最常见的读路径是什么主导路径上是否存在不必要的间接层是否存在在什么条件下这个字段组合是合法的这种需要写注释才能解释的类型如果是说明类型太松参见 Type System Discipline 的测试问题。这个形状是否会让下游逻辑变得显而易见become obvious如果下游还需要一堆条件分支才能理解数据说明形状选错了。代码层规则DRY 结构而非每一行原则在代码层面给出了四条并列规则At code level, DRY the structure, not every line. Types and data models should converge. Three similar statements still beat a premature abstraction. Prefer explicit over clever. Test behavior and edge cases, not line counts.DRY 结构而非每一行重复的结构类型、数据模型、模块形状应当收敛统一但不要为每一行相似代码强行抽象。三个相似语句仍胜过过早抽象只有三处相似的代码直接写三份比引入一个提前抽象更划算——这是对三法则Rule of Three的明确表态也与 Laziness Protocol 的最小改动解决问题一脉相承。类型与数据模型应收敛类型定义和数据模型不是两套平行的东西不应出现类型是一套、实际数据又是一套的漂移。这与 Model the Domain 的把领域编码进结构而非散布的条件分支指向同一目标。显式优于巧妙Prefer explicit over clever可读性优先于炫技与 pstack 的 unslop、no-comments 等写作与注释纪律呼应。测试行为与边界情况而非行数衡量测试质量的标准是它是否断言了用户可观察的行为和边界条件而不是覆盖率数字。这直接指向 Test Behavior, Not Implementation按用户的方式调用代码、断言用户观察到的结果如果测试在导入函数全部返回undefined时仍然通过就重写断言或删除测试。并发推论共享状态之前的必答题原则给出了一条简明却威力巨大的推论Concurrency corollary.Before sharing state between actors, ask what happens if another actor modifies this concurrently? If not nothing, isolate.在任何两个参与者actor之间共享可变状态之前先问如果另一个参与者并发地修改它会发生什么 如果答案不是什么也不会发生就把状态隔离。这一推论在 pstack 中被姊妹原则 Separate Before Serializing Shared State 展开成三步操作识别共享的可变状态——两个文件都读写同一文件、两个分支都推送、两个 API 既定义又消费默认消除共享的写目标——问它们需要一个规范对象还是在发布彼此独立的事实让每个参与者拥有自己专属的文件、键、分支或状态目录只在读/报告边界合并。两个 worker 向同一个state.json的同一个字段写各自的lastX仍是共享写indexer-state.jsonmetrics-state.json则不是。仅当共享写目标是真正的不可变约束时才用结构性手段序列化——锁文件、顺序阶段、单写者、CAS。我们需要一把锁应被视为需要核查的设计气味而不是默认答案。在 feature playbook 的吞吐检查点 中这条推论以更工程化的形式出现并行分解前必须回答四个问题——阻塞性前置步骤、独立工作流不相交的文件/服务/层可并行共享写必须串行、共享可变状态默认拆分目标仅为真实不变量序列化、最小安全分解若单 worker 最佳说出理由。脚手架优先先做对每个后续阶段都有益的事Scaffold first.If something helps every later phase, do it first. Ask does every subsequent phase benefit from this existing? CI, linting, test infrastructure, and shared types are scaffold. Sequence for option value: setup before features, tests before fixes. Keep commits small and single-purpose.判断标准只有一个问题这个东西存在是否对后续每一个阶段都有益如果答案是肯定的就最先做。原文档明确列举的脚手架scaffoldCI持续集成Linting静态检查测试基础设施test infrastructure——对应 pstack 的 tdd 技能 与 create-verification-skill 的验证思想先有可执行的验证通道再写实现共享类型shared types——再次回到数据结构优先。排序原则是为选项价值排序Sequence for option value先搭建设置后做功能setup before features环境、依赖、骨架先就位先写测试后修缺陷tests before fixes先用失败的回归测试把 bug 变成可执行的再改生产代码——这正是 tdd 技能先写失败测试、再修工作流的前提提交保持小而单一目的Keep commits small and single-purpose每个提交只做一件事便于审查与回滚也与 Sequence Work into Verifiable Units 的每个小单元以可验证状态收尾一致。脚手架优先在 pstack 代码库中的落地证据非常具体figure-it-out 技能 在 Phase B 明确引用本原则脚手架与验证先于功能Scaffold and verification come before features并要求在工作之前就建好验证装置、从改动前的状态抓取基线让检查读起来是旧值 vs 新值。architect 技能 允许设计合成作为独立提交先行落地并直接称之为foundational-thinking 原则技能的 scaffold first 模式——先提交类型与签名的骨架再填充实现。每个增量落地一个连贯抽象Each increment should land a coherent abstraction or deepen one that exists. Do not spread a new capability across callers as special-case coordination.这条规则约束增量的质量每一个增量要么落地一个连贯的抽象要么加深一个已有的抽象。禁止把一项新能力以特殊用例协调special-case coordination的方式散布到各个调用方——那会让每个调用方都背上一段特判抽象却始终缺席。这与 Model the Domain把领域编码进结构而非分散的条件分支、Minimize Reader Load数一数读者脑中的隐藏状态层数形成合力特判散布是读者负担的主要来源而一个连贯抽象可以在不增加调用链长度的情况下集中能力。先减法再搭脚手架原则的收尾是它与姊妹原则的衔接Subtraction comes before scaffolding. Remove dead code first, then lay foundations.减法先于脚手架先删除死代码再铺设地基。这直接指向 Subtract Before You Add 的完整展开——在复杂系统上做加法会放大复杂度先移除能让剩余代码更少、本质结构浮现、下一个设计通常也变得显而易见其模式包括在构建前先排定移除、在打磨前先砍到最小、为观察到的用法而非推测的边界情况设计、不添加规格之外的推测性校验器以及删除没有新内容的引用而非留下 stub。把 Foundational Thinking 与 Subtract Before You Add 连起来读可以得到一个完整的开工序列减法删死代码、折叠单调用包装、去掉冗余校验器、清除孤儿引用脚手架在更简的基础上铺设 CI、lint、测试基础设施与共享类型数据形状定义核心类型追踪访问模式选择匹配主导路径的结构逻辑按显式优于巧妙的方式填充实现让下游代码顺理成章。何时触发 Foundational Thinking根据 poteto-mode 的触发规则以下场景应当应用本原则场景本原则介入的内容任何需要写逻辑的任务先说出数据形状选择组织结构与 Model the Domain 联合触发代码跨越函数边界先经 architect 做并行设计探索把类型与签名画成骨架再实现多阶段任务按脚手架与验证先于功能排序风险最高的未知先解决并发参与者可能写共享状态先问并发推论默认消除共享、必要时结构性序列化重构/迁移先命名目标形状模块布局、类型、调用图应是什么样再移动原则使用指南 提醒不要试图背诵全部二十三条。正确用法是先通读一遍然后在发现 agent 即将跳过结构直接写逻辑时用原则名精确引导例如use foundational thinking. name the data shape and the scaffold before you write logic.落地自检清单综合原文档与仓库内配套原则完成一个任务前可用以下问题自检形状已定吗核心类型是否在写任何逻辑之前定义并选择了组织结构访问模式追踪了吗是否知道主导读写路径且结构与主导路径匹配非法状态可表示吗是否存在需要写注释解释何时合法的字段组合结合 Type System Discipline脚手架在前吗CI、lint、测试基础设施、共享类型是否先于功能就位测试是否先于修复共享状态被审问了吗每个共享写目标都回答了并发修改会发生什么默认消除了共享序列化只留给真实不变量结合 Separate Before Serializing Shared State。先减法了吗死代码是否先于新地基被移除结合 Subtract Before You Add增量连贯吗每个增量是否落地或加深了一个连贯抽象而非把能力散布为调用方特判提交小而单一吗每个提交是否单一目的、可独立审查小结Foundational Thinking 是 pstack 全部工程纪律的起点它把结构决策守护选项价值、代码决策守护简洁作为总纲用数据结构优先锁定最昂贵的决策用脚手架优先为后续所有阶段铺路用并发推论在共享状态尚未扩散时切断竞态源头再用先减法确保一切建立在最简地基上。在 pstack 中它不是一条孤立的格言而是被 poteto-mode、architect、figure-it-out 和 feature playbook 反复引用和执行的机制——从原则名到技能实现再到每个 playbook 的步骤形成了先定形状、再写逻辑的完整闭环。对任何希望让 AI 写出可维护、可并行、可验证代码的团队这都是一条值得最先内化的原则。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考