poteto-principles 是一套面向自主智能体与工程师的工程原则目录,共 24 条,用于在架构设计、重构、实现、缺陷诊断、迁移和验证等工作中系统化评估决策。
用途与目标
资料指出,工程师和 AI 智能体通常只依据当下注意力中的视角来质疑决策,未被考虑的失败模式不会浮现为问题,从而重复已知错误,例如校验分散、只修补症状、测试断言宽松、过早引入框架和抽象泄漏。该技能的目标状态是:每一个架构决策、重构步骤、实现切片和代码审查都通过这套原则系统评估,产出健壮、最小、类型安全且可自验证的系统。
主要能力:24 条工程原则
使用时应阅读 references/ 目录中与当前任务相关的全部引用资料。原则包括:
- attack-the-premise:当两个或更多共享同一前提的修复在同一关口失败时,应怀疑前提而非修复本身。
- boundary-discipline:在系统边界集中校验、类型收窄和错误处理;内部类型无条件信任;业务逻辑保持纯函数。
- build-the-lever:避免繁琐重复的手工编辑,构建可重复运行的确定性脚本、生成器或 codemod。
- encode-lessons-in-structure:同一指令重复两次后,将其从自然语言转为 linter、schema、元数据或验证检查。
- exhaust-the-design-space:对前所未有或关键的设计,先构建 2-3 个竞争原型对比权衡再决定。
- experience-first:实现便利与用户愉悦冲突时选择用户愉悦;把更少功能打磨到完美。
- explain-the-number:信任基准或指标前,先说明是什么物理资源或代码路径限制了它(“为什么不能翻倍”)。
- fix-root-causes:绝不修补症状;先复现,递归追问“为什么”,消除底层机制。
- foundational-thinking:写算法逻辑前先确定数据结构和核心领域类型。
- guard-the-context-window:将冗长的 token 转储和研究委派给子智能体,主上下文线程只保留简洁摘要。
- laziness-protocol:默认做减法;做出解决该问题的最小连贯改动。
- make-operations-idempotent:设计命令和变更器,使重复执行或中途崩溃恢复都收敛到同一目标状态。
- migrate-callers-then-delete-legacy-apis:引入替代 API 时,在同一发布波次迁移所有调用点并消除旧接口。
- minimize-reader-load:减少读者必须穿越的层数以及需要记住的工作状态。
- model-the-domain:让无效状态在数据结构中不可表示,而不是散布防御性分支检查。
- never-block-on-the-human:对可逆且可审查的操作,以合理决策继续并呈现可验证结果,而不是停滞等待。
- outcome-oriented-execution:在计划好的重构和迁移中,优先收敛到经验证的最终状态,而非保留脆弱的中间状态。
- prove-it-works:针对真实运行时环境或实际二进制验证工作,绝不通过自述、mock 或被动假设验证。
- redesign-from-first-principles:整合新需求时,像该需求从一开始就存在那样设计,而不是外挂垫片。
- separate-before-serializing-shared-state:尽可能消除可变共享状态;无法避免时,通过锁文件或显式阶段强制结构化串行化。
- sequence-verifiable-units:将工作拆成小的可验证切片,每个切片从红到绿后再继续。
- subtract-before-you-add:引入新增前先删除过时代码、未用参数、死分支和推测性脚手架。
- test-behavior-not-implementation:像调用方那样调用代码并断言字面结果;删除即使主体返回 dummy 桩也能通过的测试。
- type-system-discipline:将变体建模为标签联合;为语义原语加品牌;在边界校验外部负载;绝不用类型转换欺骗编译器。
使用方式
资料说明:当应用某条原则时,应引用其文件名并说明具体的前后变化(Cite the Principle with Evidence)。结构杠杆优先于叙述性规则:按 encode-lessons-in-structure 将重复警告转为机械化的 linter 或 schema 验证。先减后加:按 subtract-before-you-add 在添加新功能前删除死代码、未用标志和废弃抽象。技能位于 https://www.skills.sh/immamdouhaboammar/omni-skill/poteto-principles,来源为 immamdouhaboammar/omni-skill。具体的安装命令、调用接口和配置方式在资料中暂未提供。
适用场景
根据资料描述,适用于架构设计、重构、实现、缺陷诊断、迁移和验证等工程环节,既面向自主智能体,也面向人类工程师。
限制
资料未说明该技能的收费、平台支持范围、效果保证或运行依赖,这些事实暂未提供。各原则的具体实现细节需参考 references/ 目录中的引用文件,资料未逐一展开。