1. 前端技术栈对比（React vs Vue）#

2. 后端技术栈对比（TypeScript vs Python vs Java）#

1. Ponytail 极简阶梯（Lazy Senior Dev Mode）#

这是我在所有编码任务中强制贯彻的“极简阶梯”。每次要求 AI 编写或修改代码时，必须严格依序攀登：

核心信条：最优秀的代码是无需编写的代码。追求最短有效 Diff，删除优于兼容，平实优于取巧。坚决抵制任何未经明确要求的预先设计与抽象模板。

2. 明确信任边界，拒绝过度防御工程#

在 AI 写的代码里，经常能看到一种坏味道：函数入参是个内部类型，但内部还要写四五个 if (!param) return null，层层套娃，掩盖了真正的问题。

必须把系统边界与受信任内部严格切分开：

• 外部边界严防死守：
  • 所有外部输入（HTTP、爬虫、LLM 输出）必须经过强类型 Schema 解析；
  • 网络抓取前必须执行 SSRF 防御，坚决拦截私有局域网与回环地址；
  • 防范 Prompt 注入：所有检索召回的客观外部文本，必须使用明确的 XML 围栏（例如 <context_document>）进行物理隔离，并在 System Prompt 中声明该标签内全为不可信数据。
• 内部链路精炼直白：在内部模块协同中，坚决剔除假想式防御、冗余类型断言与掩盖错误的吞错兜底。

3. 注释与日志的第一性原理#

• 只描述现状，解释 WHY 不解释 WHAT：

  1
  // ❌ 错误示范：复述代码做了什么，或者记录历史原因
  2
  // 遍历用户列表并过滤掉未激活用户，曾有 Bug，原本打算用 map 实现
  3
  const activeUsers = users.filter(u => u.isActive);
  4
  
  5
  // ✅ 正确示范：说清楚为什么需要这么做、关键边界是什么
  6
  // 过滤未激活账号以避免下发批量推送时触发下游第三方通道配额熔断
  7
  const activeUsers = users.filter(u => u.isActive);

• 绝不留存“历史包袱”：严禁在注释中叙述“历史原因”、“兼容迁移前旧数据”；如果删去注释后读者依然能轻易读懂且不丢失关键边界信息，该注释即为多余，必须删除。
• 错误调用栈保全：捕获未知错误重新抛出时，必须传递 { cause: err }；日志统一使用结构化传参，英文字段名 + 中文业务提示，敏感字段强制脱敏。

4. 架构卫生准则#

• 单业务文件不超过 500 行：业务代码一旦逼近 500 行，意味着该模块的职责已经开始发散，必须优先重构模块边界。
• 删除优于兼容：重构时直接硬删除废弃逻辑，严禁在内部留存无用的 deprecated 兼容层或长期双写。若数据库迁移确实需要临时双写，必须在代码处注明移除条件与工单号（例如 ponytail: migration until M2, issue #12）。

1. SDD 实践：规格分层与工单化切片#

在写任何业务代码之前，我要求系统必须拥有以下几份“真源文件”：

• PRODUCT.md（产品真源）： 明确产品受众、核心目的与交互调性。最关键的是写上 Anti-references（反向参考风格），例如明确写明：“杜绝花哨的 SaaS 渐变、杜绝终端风格暗色刺眼配色、杜绝 AI 常见的圆润气泡对话框与慢吞吞的打字机动画”。告诉 AI 什么是丑的，比告诉它什么是美的有用得多。
• DESIGN.md（视觉真源）： 收敛整个项目的 Design Tokens，包括确定的色板（推荐现代 oklch 或规范 Hex）、字阶表、紧凑度（Density）与间距缩放。
• CONTEXT.md（领域统一语言表）： 明确业务领域中的专有名词，并列出显式的 _Avoid_ 禁用词汇。比如在文档中写清：本项目一律称呼为「基元组件」，严禁 AI 混淆使用「UI 框架」「底层库」「新基元」等自造词。这能彻底锁死 AI 在长对话中的术语漂移。

1
---
2
id: '01'
3
title: 实现基于 Argon2 的安全认证与令牌颁发
4
type: task # 可选: research / prototype / task
5
status: open # open / claimed / closed
6
blocked_by: [] # 依赖的前置工单
7
---
8

9
## 目标与出口判据
10
- 端点 POST /api/auth/login 校验凭据并签发 HttpOnly Cookie
11
- 密码校验采用 Argon2-cffi 算法
12
- 验收标准：tests/e2e/test_auth.py 真实请求全通

2. TDD 实践：告别虚假的浅层测试#

在 AI 编码中，最容易被误用的就是单元测试。AI 为了让测试跑通，会非常熟练地 Mock 掉数据库、Mock 掉网络请求、Mock 掉所有依赖函数，最后生成了一套 100% 通过的“纸面测试”——一旦联调，依然到处报错。

我将测试简化为两类最真实、最能打硬仗的形式：

1. 真实端到端测试（E2E）作为业务逻辑的唯一测试机制：
   • 前端使用 Playwright 启动真实的无头或带头浏览器，断言真实的 DOM 渲染与用户交互；
   • 后端通过 Docker Compose 启动真实的数据库、缓存、消息队列等依赖环境跑集成测试；
   • 真查库、真发网络请求，拒绝浅层 Mock。
2. 不变量测试（Invariants Testing）：
   • 针对纯算法、文本切片、分词、协议解析等无副作用模块；
   • 在写实现代码之前，先在 tests/invariants/ 清单中穷举所有边界与失败情形（空输入、非法编码、超长边界、特殊换行符）；
   • 先跑红，再写实现，全绿即收工。

1. 核心 MCP：精简到极致的黄金组合#

配置一长串不稳定的 MCP 只会拖慢推理速度。在日常开发中，我固定只用这组不可或缺的双核心：

• Context7 (Upstash) — 解决编码前的“知识滞后”：
  • 痛点：AI 模型的原生权重往往落后于现实开源库的最新版本（比如 Tailwind v4 配置方式变更、Drizzle ORM 的新 API、React 19 新语法）；
  • 解法：Context7 允许 AI 在写代码前直接按需检索并拉取最新、带版本号的官方文档和权威示例，彻底消除废弃 API 的幻觉。
• Playwright — 解决编码后的“纸上谈兵”：
  • 痛点：AI 生成的前端代码经常“在脑海中编译通过”，实际在浏览器里却布局塌陷、按钮被遮挡或有异步竞态；
  • 解法：让 AI 拥有自主操纵真实无头浏览器的能力。AI 写完页面后自己导航上去点击、看报错日志、截取屏幕排查，真正实现**“生成 → 实际运行 → 发现破损 → 自主修复”**的闭环。

2. 关键 Skills 体系#

除了工具层面，我还把成熟的工程规范沉淀为 Agent Skills：

• Matt Pocock Skills 系列（逻辑与工程护栏）：
  • /grill-me：开工前的需求拷问神器。让 AI 扮演挑剔严苛的资深架构师，逐个问题盘问我：“如果用户网络断开怎么办？”“主键冲突怎么处理？”“并发配额如何切分？”把隐藏假设在写代码前全部问清楚。
  • /sdd：自动化辅助规格定义与工单拆分。
  • /tdd：驱动严格的 Red-Green-Refactor 流程。
• Impeccable（前端审美与防“AI 塑料感”）：
  • Paul Bakaus 发起的开源设计技能，注入了 50 多条确定性的反模式检查规则；
  • 结合前文提到的 PRODUCT.md 和 DESIGN.md，使用 /critique 或 /polish，能够一键扫除 AI 经常写出的粗暴卡片套卡片、无节制渐变色和留白失衡，让界面呈现干净克制的编辑质感。
• Ponytail（极简与复杂度审查）：
  • 专治 AI 的过度设计与推测性封装本能；
  • 在 Review 阶段使用 /ponytail-review，只寻找可以删除的代码、多余的抽象层和重复轮子，坚决守卫代码库的极简底线。