Ponytail (DietrichGebert/ponytail) 深度分析报告

Codex 核验（2026-10-10）：当前 Ponytail README 已是 Ponytail 5：作者在 Claude Code、Opus 5.5、39 任务各 5 次的实验中报告代码 -53%、输出 tokens -45%、费用 -26%、时间 -41%，不是本文旧版少量 LOC 示例的通用结论。项目包含 hooks 与 JavaScript 运行时文件；核心指令是文本不代表整套集成没有运行时。Hermes 复刻方案属于未实施设计，不能凭 alwaysApply、triggers 或复制 SKILL.md 推定已有原生 hook 或每会话自动执行。

日期: 2026-06-17 | 仓库: https://github.com/DietrichGebert/ponytail | Stars: 28K+

---

目录

1. README 全面分析
2. 文件结构分析
3. 核心规则集提取（Ladder Rules 原文）
4. Benchmark 数据与方法论
5. Hermes Skill 复刻评估与方案

---

1. README 全面分析

1.1 核心理念

Ponytail 是一个”懒人高级开发”行为规范（Skill），不是工具也不是库。它将自己注入到 AI Agent 的 system prompt 中，让 agent 像”干了十年、见多识广、懒得写废话”的高级开发一样写代码。

“He says nothing. He writes one line. It works.”

1.2 架构设计

Ponytail 的架构是 “一层规则核心 + 多层适配器”：

┌─────────────────────────────────────────┐
│            AGENTS.md / 规则核心          │ ← 6 阶梯规则 + 7 条行为守则
├─────────────────────────────────────────┤
│            skills/ponytail/SKILL.md      │ ← 主技能文件（含 lite/full/ultra 层级）
├─────────────────────────────────────────┤
│  skills/ponytail-review  (过度工程审查)   │
│  skills/ponytail-audit   (全仓库审查)     │
│  skills/ponytail-debt    (技术债追踪)     │
│  skills/ponytail-help    (快速参考)       │
├─────────────────────────────────────────┤
│  hooks/                   (生命周期钩子)  │ ← SessionStart / UserPromptSubmit
│  commands/                (命令定义)      │ ← /ponytail, /ponytail-review, 等
├─────────────────────────────────────────┤
│  适配器层 (每个 agent 一个入口)           │
│  ┌──────┬──────┬──────┬──────┬──────┐    │
│  │Claude│Codex │Cursor│Windsurf│Cline│   │
│  │Copilot│Gemini│Kiro │OpenCode│ Pi  │   │
│  │OpenClaw│Aider│Antigravity          │   │
│  └──────┴──────┴──────┴──────┴──────┘    │
└─────────────────────────────────────────┘

关键设计原则：

• Single Source of Truth: 规则核心在 skills/ponytail/SKILL.md；所有 agent 适配器（.cursor/, .windsurf/, 等）都是从它同步的副本
• 指令即代码: 核心指令以文本规则注入 prompt；完整集成还包含 hooks 与 JavaScript 运行时文件
• 适配器薄层: 每个 agent 只需要一个适配器文件（规则文件、插件清单、或钩子脚本）

1.3 阶梯法则（The Ladder）

这是 ponytail 最核心的决策框架：

1. Does this need to exist?        → 不需要则跳过 (YAGNI)
2. Stdlib does it?                 → 用标准库
3. Native platform feature?        → 用平台原生功能
4. Installed dependency?           → 用已有依赖
5. One line?                       → 一行搞定
6. Only then: minimum that works   → 写最少的工作代码

每次写代码前，agent 从阶梯顶端开始，停在第一个”站得住”的阶梯。两条阶梯都能站住？选更高的那条，继续走。

1.4 三级强度模式

1.5 支持哪些 Agent

Ponytail 支持 13 个 agent/平台，分两类：

插件级（全功能：规则注入 + 命令 + 钩子）：

指令级（仅规则文件，无命令/钩子）：

1.6 配置系统

• 环境变量: PONYTAIL_DEFAULT_MODE (lite/full/ultra/off)
• 配置文件: ~/.config/ponytail/config.json ({"defaultMode": "lite"})
• Windows: %APPDATA%\ponytail\config.json
• 解析优先级: env var > config file > full (默认)

---

2. 文件结构分析

2.1 完整目录树

ponytail/
├── README.md                    # 主 README（准入文档）
├── AGENTS.md                    # ★ 最精简规则核心（26 行）
├── LICENSE                      # MIT
├── .env.example                 # 环境变量示例
│
├── skills/                      # ★ 技能文件（Core）
│   ├── ponytail/
│   │   └── SKILL.md             #   ★ 主技能：懒人开发模式（100行）
│   ├── ponytail-review/
│   │   └── SKILL.md             #   ★ 审查过度工程（56行）
│   ├── ponytail-audit/
│   │   └── SKILL.md             #   ★ 全仓库过度工程审计（40行）
│   ├── ponytail-debt/
│   │   └── SKILL.md             #   ★ ponytail: 注释债务追踪（44行）
│   └── ponytail-help/
│       └── SKILL.md             #   ★ 快速参考卡（68行）
│
├── hooks/                       # 生命周期钩子（Agent 运行时交互）
│   ├── ponytail-activate.js     #   SessionStart: 写入状态文件 + 注入 ruleset
│   ├── ponytail-mode-tracker.js #   UserPromptSubmit: 检测 /ponytail 命令切换模式
│   ├── ponytail-instructions.js #   共享指令构建器：从 SKILL.md 按级别过滤
│   ├── ponytail-config.js       #   配置解析器（env > config > default）
│   ├── ponytail-runtime.js      #   运行时工具（flag文件读写、钩子输出格式）
│   ├── ponytail-statusline.sh   #   Claude Code statusline badge (Linux)
│   ├── ponytail-statusline.ps1  #   Claude Code statusline badge (Windows)
│   ├── hooks.json               #   Codex 钩子注册
│   └── copilot-hooks.json       #   Copilot CLI 钩子注册
│
├── commands/                    # 命令定义（格式按对应平台和仓库版本核对）
│   ├── ponytail.toml            #   /ponytail [lite|full|ultra|off]
│   ├── ponytail-review.toml     #   /ponytail-review
│   ├── ponytail-audit.toml      #   /ponytail-audit
│   ├── ponytail-debt.toml       #   /ponytail-debt
│   └── ponytail-help.toml       #   /ponytail-help
│
├── .cursor/rules/
│   └── ponytail.mdc             # Cursor 规则（30行，alwaysApply）
├── .windsurf/rules/
│   └── ponytail.md              # Windsurf 规则（24行）
├── .kiro/steering/
│   └── ponytail.md              # Kiro 引导规则（29行）
├── .claude-plugin/
│   └── plugin.json              # Claude Code 插件清单
├── .codex-plugin/
│   └── plugin.json              # Codex 插件清单
├── .opencode/
│   ├── plugins/ponytail.mjs     # OpenCode 服务器插件（system.transform）
│   └── command/                 # OpenCode 命令 markdown 文件
│       ├── ponytail.md
│       ├── ponytail-review.md
│       ├── ponytail-audit.md
│       ├── ponytail-debt.md
│       └── ponytail-help.md
├── gemini-extension.json        # Gemini CLI 扩展清单
├── pi-extension/
│   ├── index.js                 # pi agent 扩展
│   ├── package.json
│   └── test/
│       ├── extension.test.js
│       └── helpers.test.js
│
├── benchmarks/                  # Benchmark 框架 + 结果
│   ├── prompts.json             # 5 个 benchmark 任务定义
│   ├── behavior.js              # 行为门控（hardware/explanation/onecheck）
│   ├── model-email.js           # Python 邮件验证执行器
│   ├── arms/                    # Benchmark 对比臂
│   │   ├── baseline.js          #   无技能（纯用户 prompt）
│   │   ├── ponytail.js          #   Ponytail (SKILL.md 全文)
│   │   ├── caveman.js           #   Caveman 对比
│   │   └── caveman-SKILL.md
│   └── results/
│       ├── 2026-06-15-llama3.2-local.md
│       └── 2026-06-16-correctness-gate-fix.md
│
├── examples/                    # 真实 model output 对比
│   ├── README.md                # 概览表
│   ├── email-validation.md      # 75 → 3 LOC
│   ├── debounce.md              # 116 → 10 LOC
│   ├── csv-sum.md               # 20 → 3 LOC
│   ├── react-countdown.md       # 267 → 9 LOC
│   └── rate-limit.md            # 128 → 10 LOC
│
├── tests/                       # 自动化测试
│   ├── behavior.test.js         # 行为门控单元测试
│   ├── correctness.test.js      # 代码正确性测试
│   ├── hooks.test.js            # 钩子测试
│   ├── hooks-windows.test.js    # Windows 钩子测试
│   ├── commands.test.js         # 命令测试
│   ├── copilot-plugin.test.js   # Copilot 插件测试
│   ├── opencode-plugin.test.js  # OpenCode 插件测试
│   ├── gemini-extension.test.js # Gemini 扩展测试
│   └── openclaw-skills.test.js  # OpenClaw 技能测试
│
├── scripts/
│   ├── check-rule-copies.js     # 检查规则副本是否同步
│   └── build-openclaw-skills.js # 从 skills/ 生成 OpenClaw 包
│
└── docs/
    └── agent-portability.md     # Agent 可移植性文档

2.2 关键文件分析

AGENTS.md（26 行）：最精简的规则核心。被大多数 agent 自动读取。所有 .cursor、.windsurf 等副本与之保持一致。

skills/ponytail/SKILL.md（100 行）：主体的技能文件。含 YAML frontmatter（名称、描述、触发器关键词）、阶梯规则、行为守则、三级强度表、输出格式规范、边界定义。hooks/ponytail-instructions.js 按 lite/full/ultra 级别动态过滤该文件的内容注入 system prompt。

hooks/ 的核心流水线：

1. ponytail-config.js → 解析模式（env > config > full）
2. ponytail-instructions.js → 读取 SKILL.md → 按模式级别过滤 → 生成 system prompt 文本
3. ponytail-activate.js (SessionStart) → 写 flag 文件 + 注入规则到 stream
4. ponytail-mode-tracker.js (UserPromptSubmit) → 检测 /ponytail 命令 → 切换模式 flag

适配器原则（来自 agent-portability.md）：

“Keep adapters thin. When a host supports skills or hooks, point it at the existing skills/ and hooks/ files. When a host only supports project instructions, keep its copied rule text aligned with AGENTS.md.”

---

3. 核心规则集提取

3.1 The Ladder（阶梯六则）— 原文逐条

以下直接来自 skills/ponytail/SKILL.md（权威来源）:

1. Does this need to exist at all? Speculative need = skip it, say so in one line. (YAGNI)

2. Stdlib does it? Use it.

3. Native platform feature covers it? <input type="date"> over a picker lib, CSS over JS, DB constraint over app code.

4. Already-installed dependency solves it? Use it. Never add a new one for what a few lines can do.

5. Can it be one line? One line.

6. Only then: the minimum code that works.

The ladder is a reflex, not a research project. Two rungs work → take the higher one and move on. The first lazy solution that works is the right one.

3.2 Rules（七条行为守则）— 原文逐条

来自 skills/ponytail/SKILL.md：

• No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
• No boilerplate, no scaffolding “for later”, later can scaffold for itself.
• Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
• Fewest files possible. Shortest working diff wins.
• Complex request? Ship the lazy version and question it in the same response, “Did X; Y covers it. Need full X? Say so.” Never stall on an answer you can default.
• Two stdlib options, same size? Take the one that’s correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
• Mark deliberate simplifications with a ponytail: comment (// ponytail: this exists), simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: # ponytail: global lock, per-account locks if throughput matters.

3.3 Output 规范（原文）

Code first. Then at most three short lines: what was skipped, when to add it. No essays, no feature tours, no design notes. If the explanation is longer than the code, delete the explanation, every paragraph defending a simplification is complexity smuggled back in as prose. Explanation the user explicitly asked for (a report, a walkthrough, per-phase notes) is not debt, give it in full, the rule is only against unrequested prose.

Pattern: [code] → skipped: [X], add when [Y].

3.4 When NOT to be lazy（原文）

Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, anything explicitly requested. User insists on the full version → build it, no re-arguing.

Hardware is never the ideal on paper: a real clock drifts, a real sensor reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not just less code, the physical world needs tuning a minimal model can’t see.

Lazy code without its check is unfinished. Non-trivial logic (a branch, a loop, a parser, a money/security path) leaves ONE runnable check behind, the smallest thing that fails if the logic breaks: an assert-based demo()/__main__ self-check or one small test_*.py. No frameworks, no fixtures, no per-function suites unless asked. Trivial one-liners need no test, YAGNI applies to tests too.

3.5 ponytail-review 审查标签（原文）

Tags:

• delete: dead code, unused flexibility, speculative feature. Replacement: nothing.
• stdlib: hand-rolled thing the standard library ships. Name the function.
• native: dependency or code doing what the platform already does. Name the feature.
• yagni: abstraction with one implementation, config nobody sets, layer with one caller.
• shrink: same logic, fewer lines. Show the shorter form.

3.6 ponytail-audit 搜索目标（原文）

Deps the stdlib or platform already ships, single-implementation interfaces, factories with one product, wrappers that only delegate, files exporting one thing, dead flags and config, hand-rolled stdlib.

3.7 ponytail-debt 债务追踪（原文）

Every deliberate ponytail shortcut is marked with a ponytail: comment naming its ceiling and upgrade path. This collects them into one ledger so a deferral can’t quietly become permanent.

---

4. Benchmark 数据与方法论

4.1 测试设计

4.2 核心数字

4.3 具体任务对比（Haiku 4.5）

4.4 正确性验证（2026-06-16 修正 gate 后）

修复了 benchmark 框架的两个 bug（未围栏代码计为 0、debounce 测试检查了未要求的输出），n=20 重新运行后：

4.5 已知限制

---

5. Hermes Skill 复刻评估与方案

5.1 可行性评估：★★★☆（高度可行）

5.2 方案 A：轻量复刻（推荐，2-3天内）

创建一个名为 ponytail 的 Hermes skill，结构：

~/.hermes/skills/ponytail/
├── SKILL.md              # ★ 主 skill：含阶梯规则 + 三级强度 + 输出规范
├── SKILL.variants/
│   ├── lite.md           #   lite 级别变体
│   └── ultra.md          #   ultra 级别变体
├── commands/
│   ├── ponytail-review   #   (可选) 审查命令
│   └── ponytail-debt     #   (可选) 债务追踪命令
└── hooks/
    └── ponytail-config   #   (可选) 配置持久化脚本

SKILL.md 内容方案：直接基于 skills/ponytail/SKILL.md（100行），做以下调整：

1. 修改 YAML frontmatter → 适配 Hermes 格式（name, description, triggers）
2. 去除 Claude/Codex 专属的钩子指令
3. 修改输出模式：Hermes 使用 Code-first + description pattern
4. 添加 # Status 部分，让 agent 在每次响应时检查 ponytail 是否 active

核心规则（SKILL.md 正文）直接从 ponytail 复制：

• 阶梯六则（逐字）
• 七条行为守则（逐字）
• 输出规范（微调：Hermes 用 terminal + patch + write_file 工具链）
• 不做懒的边界（逐字）
• 三级强度表（逐字）

5.3 方案 B：深度复刻（含完整工具链，1周）

创建 5 个 Hermes skills + 配置系统：

额外实现：

• 配置持久化：~/.hermes/config.yaml 添加 ponytail_mode: full|lite|ultra|off
• 规则一致性检查：借鉴 scripts/check-rule-copies.js，确保多个 skill 间规则同步
• benchmark suite：将 ponytail 的 5 个 benchmark 任务移植为 Hermes 的测试命令

5.4 Hermes 特有优势

5.5 复刻中需要处理的关键差异

1. 触发机制：原版用 hooks 每个 session 自动激活 → Hermes 的自动触发需核对宿主实现；不得直接假设 SKILL.md 支持 alwaysApply: true
2. 模式切换：原版用 flag 文件持久化 → Hermes 用 skill 的 variant/parameter，或 ~/.hermes/config.yaml
3. 状态持久化：原版 /ponytail ultra 写入 ~/.claude/.ponytail-active → Hermes 需自己的配置存储
4. 输出格式：原版期望 code-first + 短注释 → 可追加 Hermes 的 tool call 模式（先用 write_file 写代码，再用注释说明跳过项）

5.6 推荐实施方案

Phase 1 (1天): 核心 skill
├── 创建 ~/.hermes/skills/ponytail/SKILL.md
│   ├── 直接移植 AGENTS.md 的 26 行精简规则
│   ├── 添加 Hermes 工具使用指南（terminal + patch + write_file）
│   └── 配置 triggers: ["ponytail", "be lazy", "yagni", "simplest solution"]
└── 创建 ~/.hermes/skills/ponytail-review/SKILL.md
    └── 过度工程审查指令

Phase 2 (1天): 增强
├── 添加 lite/full/ultra 变体支持
├── 添加 ponytail-audit / ponytail-debt
├── 添加 ~/.hermes/config.yaml 的 ponytail_mode 配置
└── 端到端测试：用 5 个 benchmark 任务验证 LOC 减少

Phase 3 (1天): 精细化
├── 创建 benchmark 测试（移植 ponytail 的 5 个任务）
├── 编写中文帮助文档
├── 添加 `ponytail:` 注释模板到 Hermes 的 write_file 工具提示
└── 确保与现有 workflow（profile manas）兼容

5.7 风险与缓解

---

总结

Ponytail 本质上是一个 极致的 prompt 工程范式，不是什么复杂的技术。它的核心价值在于：

1. 决策框架（The Ladder）：将 YAGNI 原则转化为逐级检查的流程
2. 行为约束（Rules）：7 条具体的编码纪律
3. 输出格式（Code-first + terse note）：减少无意义的 prose
4. 审查工具（review/audit）：让 agent 可以自我审查
5. 标记机制（ponytail: comments）：让故意的简化可追踪

对 Hermes 的复刻建议：采用方案 A，直接从 AGENTS.md 的 26 行精简规则开始，优先保证核心阶梯规则 + 行为守则的完整性，再逐步添加 review/audit/debt 子技能。Ponytail 的设计哲学（薄的适配器层、知识注入、纯文本规则）与 Hermes 的 skill 系统天然契合，复刻成本低、回报高。

关键 quote 总结这一哲学：

“Lazy code without its check is unfinished. Explanation the user explicitly asked for is not debt. The shortest path to done is the right path.”