# Ponytail 精简实现口径（KB 集成版）

> 本文件是 KB 流程 **Ponytail 精简实现** 细则的**唯一出处**，由 SKILL.md 核心原则与 `/kb-design`、`/kb-plan`、`/kb-apply`、`/kb-review`、`/kb-archive` 引用。
>
> 来源：蒸馏自 [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) 的 YAGNI / 删法优先思想，**非**整包复制其 rules 或 hooks；已适配本 monorepo 与 AGENTS 约定。

## 一、定位

- **作用阶段**：design / plan / apply / review / archive；**不**替代 KB 主流程、manifest 白名单、CodeGraph 硬门禁（项目级 MCP + `codegraph_*` 可用）、归档顺序。
- **作用对象**：子 Agent 写**业务代码**时的决策与评审；**不**改变知识库十段式、变更文档四段式结构。
- **与 lite 路由的关系**：Ponytail 约束**实现粒度**；能否走 `/kb-lite` 仍按 SKILL 路由打分与硬闸门判定，二者独立。

## 二、六阶决策梯（写代码前必停）

在 `03` 实现范围内，子 Agent 写任何业务代码前按序停在**第一档成立**处：

1. **这功能需要存在吗？** → 否：不做（YAGNI）；若与 `01`/`02`/`03` 冲突，报告主 Agent，不得自行删需求。
2. **标准库 / 语言内置能搞定吗？** → 是：直接用（Dart `dart:`、Rust `std`、SQL 内置函数等）。
3. **平台 / 框架原生能力能搞定吗？** → 是：直接用（Flutter 内置 widget、Riverpod 已有模式、Axum/gRPC 既有中间件等）。
4. **项目已安装依赖能搞定吗？** → 是：复用；**禁止**为单点需求新增 pub/crate/npm 包，除非 `02`/`03` 已明确批准。
5. **能一行 / 一处改完吗？** → 是：就一处。
6. **最后才写**：满足 `03` 验收标准与接口契约的**最小**实现。

**删法优先**：能删则删；能改现有文件则不新建；能 inline 则不抽 mixin/notifier/helper，除非 `02`/`03` 已要求分层。

## 三、硬红线（永远不能「懒」）

以下**不得**为省代码而省略（与 Ponytail 原文及 KB 高风险闸门一致）：

- 信任边界输入校验（HTTP/gRPC/客户端入参、支付 token 等）
- 防**数据丢失**的错误处理与事务语义（资金、订单、权限）
- 安全：密钥/令牌、权限判定、审计敏感路径
- 无障碍：用户可见 UI 的必要语义（若产品/设计已要求）
- **`01`/`02`/`03` 明确要求的业务语义**（路由、状态机、proto 枚举、文案含义）
- 仓库 **AGENTS** 硬约束：proto 枚举不得私造、中文注释与关键日志、SQL 分层等

## 四、与 AGENTS 冲突消解

| Ponytail 原文 | 本仓库 AGENTS | KB 集成口径 |
|---|---|---|
| 非平凡逻辑留 assert 自检 / 小测试 | **apply 不写**单元/集成测试脚手架 | **不引入** Ponytail 测试要求；最小验证 = `03` 验收 + CodeGraph；Playwright/契约在 `/kb-test` 按需补写 |
| 全局 always-on rules + hooks | KB 阶段式子 Agent prompt | 仅在 design/plan/apply/review/archive **命令与子 Agent prompt** 中注入，不复制整包 `.mdc` |
| ultra/lite/full 档位 | KB lite/standard/hotfix-lite | **不引入** Ponytail 档位；只用本节六阶梯 |

## 五、`ponytail:` 注释约定

对**有意**接受的简化（性能上限、算法朴素、临时全局锁等），在代码中加中文注释，格式：

```dart
// ponytail: <已知上限>；升级路径 → <具体改法>
```

```rust
// ponytail: O(n²) 扫描，列表 <200 条可接受；升级路径 → 按 user_id 索引查询
```

- 有已知 **ceiling** 时必须写清上限与 **upgrade path**。
- 禁止用 `ponytail:` 标记「未做需求要求的功能」——那是 YAGNI 跳过，不需要注释。
- 归档时由 `/kb-archive` 从 diff  harvest 到 `05-summary.md` §3.1（见 kb-archive 命令）。

## 六、各阶段要求摘要

| 阶段 | 要求 |
|---|---|
| `/kb-design` | `02` §2 须回答最小方案三问（见 kb-design）；新增抽象/依赖须在 §2 写 YAGNI 依据 |
| `/kb-plan` | 每条 `T{n}` 验收标准含「无 02/03 未要求的抽象层与新依赖」；禁止「预建通用层」任务，除非 `02` 已写清 |
| `/kb-apply` | 子 Agent prompt 注入六阶梯 + `ponytail:` 约定；不得扩大 `03` 实现范围 |
| `/kb-review` | focused：Agent #3 加精简检查；full：并行 Agent #6（ponytail-review 口径）；**默认不阻断 archive**（见下节） |
| `/kb-archive` | `05-summary` §3.1 表格 harvest `ponytail:`；无则写「无」 |

## 七、精简评审（ponytail-review 口径）

仅评**过度工程**，不替代 Agent #2 Bug、Agent #5 安全/性能正确性评审。

**标签**（写入 `04-review.md` §3 或 focused 结论）：

| 标签 | 含义 |
|---|---|
| `delete:` | 死代码、无人用的配置/灵活性 |
| `stdlib:` | 手搓标准库已有能力 |
| `native:` | 新依赖或冗长代码做平台原生能做的事 |
| `yagni:` | 单实现抽象、无调用者的中间层 |
| `shrink:` | 同等逻辑可更少行数 |

**输出格式**（每条一行）：`位置 → 删什么 → 用什么替代`（多文件用 `path:L..`）。

**结尾**：`net: -N lines possible` 或 `Lean already. Ship.`

**评分与归档**：

- 精简建议默认记入 `04-review.md` **§3 警告**，评分 **< 75 不阻断** `/kb-archive`。
- 用户/团队若采纳精简建议，走 `T-FIX-{n}` 或下一轮 apply；若接受 over-engineering 遗留，可写入 `accepted_debt`（与评审四态一致）。
- **禁止**将 AGENTS「不写测试」、manifest 白名单、中文注释要求标为 bloat。

## 八、Monorepo 快速对照

| 端 | 优先复用 | 慎增 |
|---|---|---|
| Flutter | 现有 widget/provider/notifier/mixin 模式 | 新 package、新 mixin 层、重复 util |
| Rust | `std`、已有 repository/service 模式 | 新 crate、trait 仅单实现 |
| Quasar | 现有 composable、页面 mixin | 新全局 store、重复 API 封装 |
| Proto | 已有 message/enum | 客户端私造枚举映射 |

查复用点：**必须先 CodeGraph**（`codegraph_explore` / `codegraph_search`），再读具体文件。