4.1 AGENTS.md 是「地图」，不是「百科全书」#

踩过的坑：一开始把所有规则塞进一个大 AGENTS.md，结果：

• Context 是稀缺资源：大文件挤掉了任务、代码、相关文档
• 指导过载 = 没有指导：当一切都”重要”，一切就都不重要
• 立即腐烂：变成陈旧规则的坟场，智能体无法判断哪些还有效
• 难以机械校验：单个 blob 无法做覆盖率/新鲜度/所有权检查

最终方案（AGENTS.md ≈ 100 行，纯入口 + 索引）：

1
AGENTS.md            # 入口，目录索引
2
ARCHITECTURE.md      # 顶层架构
3
docs/
4
├── design-docs/     # 设计文档 + index.md + core-beliefs.md
5
├── exec-plans/      # 执行计划（一等公民工件）
6
│   ├── active/
7
│   ├── completed/
8
│   └── tech-debt-tracker.md
9
├── generated/       # 生成的文档（如 db-schema.md）
10
├── product-specs/   # 产品规格
11
├── references/      # 外部参考（design-system-llms.txt 等）
12
├── DESIGN.md
13
├── FRONTEND.md
14
├── PLANS.md
15
├── PRODUCT_SENSE.md
16
├── QUALITY_SCORE.md
17
├── RELIABILITY.md
18
└── SECURITY.md

配套机制：

• 渐进式披露：智能体从小切入点起步，文档指引下一步去哪查
• 专职 lint + CI 校验：知识库的新鲜度、交叉链接、结构正确性
• doc-gardening agent：定期扫描过时文档，发起修复 PR

4.2 仓库 = 唯一记录系统（Source of Truth）#

残酷事实：

从智能体角度看，运行时在 context 里访问不到的东西 = 不存在。

Google Docs、Slack 讨论、同事脑子里的隐性知识——智能体都看不到。只有版本控制的、纯文本的、可被 grep 的工件才存在。

那次让团队达成架构共识的 Slack 讨论？如果智能体无法发现它，它就会像迟到三个月入职的新人一样对此一无所知。

对应行动：所有重要决策、品味偏好、踩坑经验都必须落地到仓库 Markdown，包括团队的 emoji 偏好（原文真这么说）。

4.3 目标是「智能体可读性」，不是人类可读性#

最反直觉的一条：

生成的代码不总是符合人类的风格偏好，这也没关系。只要输出是正确的、可维护的，并且对未来的智能体运行而言清晰易读，就算达标。

取舍倾向：

4.4 严格架构约束（早期就上）#

1
业务域内部：Types → Config → Repo → Service → Runtime → UI
2
横切关注点（认证、连接器、遥测、Feature Flag）→ 必须经过 Providers 单一接口
3
所有规则用「自定义 linter（Codex 写的）+ 结构测试」机械强制

关键洞察：

这种架构通常要等到你拥有数百名工程师时才会推迟。对编码智能体来说，这是早期先决条件：有了约束，速度才不会下降，架构才不会漂移。

自定义 lint 的特殊设计：错误信息里直接嵌入修复指令，因为下一个读到的就是智能体。

4.5 让应用对智能体「直接可读」#

人类 QA 是固定瓶颈，所以一切都要让智能体能直接看、直接验：

4.6 吞吐量改写了合并理念#

1
传统软件工程：阻塞性合并门、零容忍 flaky test
2
智能体优先：    PR 短命、flaky test 后续重跑、纠错成本低、等待成本高

在低吞吐量环境中，这样做是不负责任的。在这里，这通常是正确的选择。

4.7 熵 + 垃圾回收（解决 AI 残渣）#

最初：每周五全员花 20% 时间清理 “AI 残渣” → 不可扩展

最终方案：

• 编码 “黄金原则”（机械化、强主观的规则）
• 后台跑 Codex 任务批量扫描偏差、更新质量等级、发起重构 PR
• 大多数清理 PR < 1 分钟即可审完自动合并
• 类比：技术债 = 高息贷款，每天小额还 >> 季度大爆发还

例子：

1. 优先用共享 utility，不要手工 helper —— 不变式集中管理
2. 不允许 “YOLO 式” 探测数据 —— 必须验证边界或用类型化 SDK

🎯 高优先级（立刻可借鉴）#

1. CLAUDE.md ≤ 100 行原则

   • 把 ~/.claude/CLAUDE.md 砍成纯入口 + 链接，详细规则下沉到 docs/references/*.md
   • 当前已在膨胀，需要 GC

2. markdown/ 目录加 lint

   • 写简单 CI / pre-commit hook：检查 frontmatter 完整性、wikilink 死链、文件命名规范
   • 这是个人版的 “doc-gardening agent” 雏形

3. 决策记录系统

   • 重要技术决策（Token 缓存机制、wechat-skill 选型）必须落到 markdown
   • 已经在做（笔记 + memory.md），但缺少 “索引页 + 主题地图”

4. 品味编码到 lint，不是放在 review 评论里

   • “复用 utility > 手写 helper” 类规则，写成 ESLint plugin
   • Vue 项目可参考

🎯 中优先级（中长期）#

5. 借鉴 docs/ 目录结构

   • docs/superpowers/ 已经有 plans + specs 雏形，可以扩展
   • 加 exec-plans/{active,completed,tech-debt-tracker.md}
   • 加 references/ 存外部库的 *-llms.txt 文档（claude-mem、wechat-cli 等）

6. session-report 进化方向

   • 本质就是 harness engineering 的可观测性栈
   • 让 Claude Code 的运行状态对下次的 Claude Code 直接可读

🎯 思想冲击（理念层）#

7. 重新定义自己的角色

   • 现在是”AI 增强的前端工程师”
   • 下一步：“AI 工程的环境设计师”——杠杆点是设计 AGENTS.md/Skills/Hooks 这些 harness，而不是单纯让 Claude 帮写代码

8. 接受”智能体可读 > 人类可读”

   • 别因为代码不够优雅就追着改
   • 标准是：下一次 Claude Code 读懂这段代码的成本 + 改对的概率
   • 这跟”代码必须优雅”的本能会有冲突