pstack数据形状优先原则数据结构如何决定代码设计【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude在 pstack 这套 Agent 工作流里数据形状优先原则data shape first是贯穿所有编码任务的第一性法则先给数据命名、定形状、选组织方式再动手写逻辑。pstack 是一个面向 Claude Code、Codex、Pi、OpenCode 等 Agent 框架的严格工作流技能栈把数据结构决定代码设计从口号落实成了可执行的规则。本文将带你快速理解这条原则的来龙去脉、常用结构选型以及它在 pstack 中是如何被强制执行的。快速上手先认识 pstackpstack 的核心入口是poteto-mode你只需告诉它目标例如修复翻页时搜索条件重置的问题它会自动选择正确的工作流——复现、调查、委托实现、重跑验证。其中一条硬性规则直接体现了本文主题任何代码任务 →先命名数据形状再按领域建模原则选择其组织结构。你可以把它理解为 pstack 的宪法级条款写在 poteto-mode/SKILL.md 中并在feature与refactoring两个 playbook 里反复触发。什么是数据形状优先为什么结构决定设计pstack 把这条原则拆成两层文件来阐述地基层principle-foundational-thinking 开宗明义——先拿到正确的数据形状再写逻辑。尽早定义核心类型追踪每一个访问模式选择与主路径匹配的结构。执行层principle-model-the-domain 解释了为什么散落的布尔值、跨文件重复的形状假设、铺开的分支判断都是偶然复杂度而一个与领域匹配的结构能让非法状态不可表示直接删掉分支。一句话总结其因果链数据形状错了 → 逻辑必须不断打补丁if/else 链条越来越长数据形状对了 → 逻辑变得显而易见很多分支从类型层面消失写代码时做对很便宜事后补救则读起来像重构于是被无限拖延 所以数据结构如何决定代码设计不是偏好问题而是维护成本问题。4 种常用数据形状技术从布尔地狱到领域结构principle-model-the-domain给出了一个选型清单可以直接当作检查表使用信号坏味道优先选择的数据结构散落的布尔标志、生命周期检查状态机state machine松散参数、重复的形状假设带类型的对象/模型typed model分支判断散布在多个文件里映射表、注册表、判别联合registry / discriminated union临时拼凑的状态修改Reducer 或命令/事件模型按加载→校验→转换→保存顺序组织的模块围绕一个领域知识体组织的模块执行顺序 ≠ 所有权同时它明确提醒不要强行抽象。如果当前形状已经清晰、局部、且不太可能增长优先选择无聊但直白的代码。怀疑任何增加了一层间接却没有删掉分支、重复规则或非法状态的抽象。 如何自检是否跳过了这一步两个经典信号新功能让既有 if/else 链条多长了一个分支或者出现第二个必须与第一个保持同步的布尔值。类型系统纪律让非法状态在编译期消失数据形状要真正落地需要类型系统做守卫。principle-type-system-discipline 把它总结为一句狠话类型检查器是证明助手。对 TypeScript 项目pstack 还有专门的 typescript-best-practices 规则表核心几条判别联合优先用kind字面量区分变体杜绝可选字段袋子构造式建模通过形状的构造方式让非法值根本无法产生非空列表 头 尾而不是长度0 的列表品牌化原语UserId和OrderId底层都是字符串但类型上不可互换禁止as强转每一次强转都是等待发生的运行时崩溃外部数据先解析JSON、RPC 载荷、CLI 参数在边界处解析为具名领域类型边界内信任类型其中最有意思的自检问题是你能不能写一行注释来解释某个字段组合何时合法 如果能——说明类型太宽松该拆成联合类型了。5 个设计红旗数据形状出错的典型症状pstack 的architect技能在综合多个候选设计前会用一份红旗清单逐一筛查文件在 design-red-flags.md。与数据形状相关的有五个浅模块暴露一大堆接口却几乎不隐藏复杂度——形状选错时最常见的结果信息泄漏同一个表示细节出现在多个模块改动需要多处协调编辑时间分解按执行顺序而非知识所有权组织模块同一套规则在每个阶段重复所有权分裂多个模块写同一份状态规则逐渐漂移直通方法原样转发参数只加一层间接而不隐藏任何复杂度 配合 principle-separate-before-serializing-shared-state 的原则当两个执行者可能写同一份状态时先问是否真的需要共享能消灭共享就先消灭——并发冲突往往是数据形状问题的运行时表现。如何在 pstack 中强制执行这条原则原则之所以在 pstack 里不是建议而是流程靠的是三处工程化设计架构先行architect 技能要求在写代码前就勾勒类型、函数签名、类形状与模块边界函数体留not implemented实现与草图偏离时视为信号而非摩擦如果反复出现同形状的绕行方案直接推倒重来Phase E: Scrap设计空间穷尽principle-exhaust-the-design-space 要求对没有先例的决策先做 2-3 个结构上互不相同的原型再定夺——第一个形状的第二种口味不算数自动触发poteto-mode把上述原则织入了feature与refactoringplaybookAgent 在委托子代理写代码前必须携带具名数据形状 组织结构这一上下文否则任务不成立完整技能清单与斜杠命令可查阅 docs/reference.md维护说明见 CHANGES.md。小结把判断前置到数据层数据形状优先原则的价值可以用三句话带走形状错了逻辑就是补丁堆形状对了很多分支根本不存在用类型系统把非法状态变成编译不过把运行时惊喜前移为编译期报错在写代码之前做结构决策最便宜——pstack 把这一点做成了强制流程而不是口头规范如果你正在管理一个由 Agent 参与编码的项目这套原则同样可以直接抄作业给数据命名、追踪访问模式、匹配主路径选结构、用类型删分支——这比任何代码规范都能更早暴露设计问题。【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考