Ponytail 项目落地指南

本文是一份可复制到其它项目的 agent 协作规范。目标不是让 agent 少做事而是让 agent 少写不必要的代码先理解真实问题再优先复用、删除和最小改动。适用场景Ponytail 适合放进项目级规则文件例如AGENTS.mdCLAUDE.md.codex/或团队自定义 agent 规则目录项目治理文档中的 “Agent Working Rules” 章节它适用于需求开发、缺陷修复、代码评审、重构和测试补强。它不替代项目已有的安全、发布、OpenSpec、测试或代码规范而是作为“如何选择最小正确实现”的决策层。核心原则Ponytail 的原则可以概括为一句话高效不是跳过理解而是在理解之后只做必要的事。在项目里使用时应要求 agent 先读相关代码路径再做实现选择。小 diff 只有落在正确位置才有价值不理解链路就做出的“小改动”通常只是把 bug 挪到另一个地方。决策阶梯每次准备新增代码前按下面顺序停一下。第一个能解决问题的层级就是优先方案这个东西真的需要做吗如果需求可以通过配置、文档、现有流程或澄清边界解决就不要写代码。代码库里是否已经有现成能力先找 helper、util、service、assembler、codec、parser、test fixture、已有模式。同一个语义尽量收口到一个地方不要复制第二套。标准库是否已经能解决Java 项目优先考虑 JDK、Spring、Jackson/Fastjson、Apache Commons 等当前栈内能力。平台或框架原生能力是否覆盖Spring 配置、Bean 生命周期、校验注解、已有中间件能力优先于手写框架。现有依赖是否已经能解决只使用已经引入且适合当前模块边界的依赖。不为了少写几行代码新增依赖。是否可以是一个小的本地改动能用局部判断解决就不新增抽象。能改共享根因就不在每个调用方补丁。最后才写新的最小实现。只覆盖当前需求和明确的兼容边界。不顺手做无关重构。项目级规则模板下面这段可以直接放进项目根目录的AGENTS.md或CLAUDE.md## Ponytail Rules Use Ponytail as an efficiency discipline, not as a shortcut around understanding. Before adding code, use the first rung that works: 1. Does this need to be built at all? 2. Does the codebase already have a helper, pattern, or service for it? 3. Can the standard library or existing framework APIs do it? 4. Can an existing project dependency do it without adding a new dependency? 5. Can this be a small local change instead of a new abstraction? 6. Only then write the minimum code that solves the real flow. Project guidance: - Prefer deletion, reuse, and boring local fixes over new layers. - Do not add dependencies unless the existing stack cannot reasonably solve the problem. - Do not introduce abstractions for one caller unless the surrounding code already has that pattern. - Fix shared root causes once instead of patching only the reported path. - Keep changes scoped to the requested behavior and the touched module boundary. - Mark intentional simplifications with a ponytail: comment only when there is a known ceiling and a clear upgrade path. Not optional: - Read the relevant code path before deciding the smallest change. - Preserve validation, error handling, security,>在日常开发中怎么用需求开发需求进入实现前先把 Ponytail 决策阶梯当作方案评估清单是否已有相同链路或邻近 lane 可以复用是否已有 DTO / codec / assembler / parser 可以扩展是否应该改共享边界而不是在 controller、service、test 里各补一段是否需要新字段、新表、新接口还是已有协议字段能表达如果需求有 OpenSpec 或 PRDPonytail 不能删掉 SHALL 规则。它只能帮助选择更小、更稳的实现路径。缺陷修复缺陷报告通常描述的是症状不一定是根因。使用 Ponytail 时应默认复现或定位症状。grep 相关函数、字段、事件名和调用方。找共享根因。在共享边界修一次。增加最小回归测试或验证命令。不要只修用户刚好点到的路径。如果同一个 parser、normalizer、route、codec 被多个入口使用优先修共享函数。代码评审评审时可以用 Ponytail 问这些问题这个新类是否只有一个调用方这个 helper 是否只是把一行代码换了个名字这个配置项是否真的需要暴露这个异常包装是否让错误更清楚还是只增加层级这个测试是否需要完整 Spring 上下文还是普通单测足够是否有重复逻辑可以收口到已有函数评审输出应优先指出可删除、可复用、可局部化的改动。重构Ponytail 不鼓励“大扫除式重构”。推荐顺序是先围绕当前需求修最小路径。如果重复逻辑阻碍修复再抽共享函数。如果抽象已经有两个以上真实使用点再考虑提升层级。如果只是看起来更整齐但不降低风险、不减少重复、不改善测试就先不做。什么不能被 Ponytail 省掉这些内容不属于“可偷懒范围”信任边界的输入校验防止数据丢失的错误处理鉴权、权限、脱敏和安全约束金融、法务、医疗等高风险语义的准确性必要的兼容逻辑用户或 spec 明确要求的行为非平凡逻辑的测试或可运行验证发布、回滚、迁移、灰度相关安全动作一句话Ponytail 可以减少代码量不能减少责任。ponytail:注释怎么写只有在有意选择一个简化方案并且知道它的上限时才写ponytail:注释。好例子// ponytail: linear scan is enough for the current 50 item payload; replace with a map if this becomes hot.不好的例子// ponytail: simple implementation注释必须说明为什么当前简化足够上限在哪里未来什么时候升级推荐落地方式在项目根目录新增或更新AGENTS.md。只放“规则入口”和 Ponytail 决策层不复制所有团队流程。如果项目已有 OpenSpec、ADR、playbook、技能目录在AGENTS.md里导航到它们。新需求开始前让 agent 先读相关 spec 和触达代码再应用 Ponytail 决策阶梯。提交前要求 agent 汇报复用了什么没有新增什么为什么这是最小正确改动跑了什么验证提交前检查清单可以把下面清单贴到 PR 模板或 agent 收尾要求里我读过被修改链路的主要调用方。我确认没有已有 helper / service / codec 可以直接复用。我没有新增不必要依赖。我没有为了一个调用点新增抽象。我没有顺手做无关重构。我保留了必要的校验、错误处理和安全边界。非平凡逻辑有测试或可运行验证命令。我能说明这次改动为什么是最小正确改动。给其它项目的最小复制版如果只想快速落地复制下面这段即可## Ponytail Before writing code, first ask: 1. Is this needed? 2. Does this already exist in the codebase? 3. Can the standard library or framework do it? 4. Can an existing dependency do it? 5. Can this be a local change instead of a new abstraction? 6. Only then write the smallest correct implementation. Rules: - Reuse before writing. - Delete before adding. - Shared root cause before per-caller patches. - No new dependency unless necessary. - No abstraction for one caller. - Keep validation, error handling, security,>