@geminix/gxpm 0.1.0

package/docs/plans/docs-knowledge-system-plan.md

@@ -0,0 +1,31 @@
+# docs/ 结构化知识沉淀体系实现计划
+
+## 概述
+
+在 docs/ 下建立四个结构化子目录（brainstorms、plans、solutions、specs），定义分类约定、命名规范和 frontmatter 标准，并填充初始示例文档。
+
+## 实施步骤
+
+1. 创建 `docs/brainstorms/` 目录，添加 README.md 说明需求文档分类约定
+2. 创建 `docs/plans/` 目录，添加 README.md 说明实现计划分类约定
+3. 创建 `docs/solutions/` 目录，添加 README.md 说明最佳实践与恢复手册分类约定，定义 frontmatter 模板
+4. 创建 `docs/specs/` 目录，添加 README.md 说明 host 平台规范镜像分类约定
+5. 迁移现有 docs/ 子目录内容到对应分类，或在根目录保留并建立索引
+6. 在 `docs/brainstorms/` 创建至少 1 份 `*-requirements.md` 示例
+7. 在 `docs/plans/` 创建至少 1 份 `*-plan.md` 示例
+8. 在 `docs/solutions/` 创建至少 3 份最佳实践/故障恢复手册（含完整 frontmatter）
+9. 在 `docs/specs/` 创建 claude.md、codex.md、cursor.md 三份 host 规范镜像
+10. 更新 docs/ 根目录 README.md 说明整体结构和导航
+11. 运行 `bun run check` 验证无破坏
+
+## 风险评估
+
+- 现有 docs/ 子目录可能与新的分类体系冲突，需要明确是迁移还是并行保留
+- frontmatter 标准过于严格可能导致后续维护负担
+- docs/specs/ 的 host 规范镜像需要与 hosts/ 代码目录保持同步，存在漂移风险
+
+## 验证方法
+
+- 目录结构符合 acceptance-contract 7 条标准
+- 所有 solutions/ 文档通过 frontmatter 完整性检查
+- `bun run check` 通过

package/docs/plans/spec-kit-sdd-adoption-plan.md

@@ -0,0 +1,305 @@
+# gxpm 引入 Spec-Driven Development 能力实现计划
+
+> 计划日期：2026-05-05
+> 依据：`docs/research/spec-kit-study.md`
+> 视角：技术架构师，聚焦架构约束与最小安全路径
+
+---
+
+## 一、概述
+
+### 1.1 目标
+
+将 Spec Kit 的 Spec-Driven Development (SDD) 核心能力内化为 gxpm 的第一方能力：
+- **宿主适配注册表**：统一抽象 Claude、Codex、Cursor、Kimi 等宿主，消除硬编码适配
+- **四层可扩展性栈**：建立 Override > Preset > Extension > Core 的模板/命令优先级解析机制
+- **声明式工作流引擎**：将 gxpm 的 phase gate（triage→plan→dispatch→…→land）从硬编码升级为 YAML 声明式状态机
+- **SDD 宪法嵌入**：将 Nine Articles 融入 gxpm 开发契约，建立规格优先的执行纪律
+
+### 1.2 范围
+
+| 在范围内 | 不在范围内（非目标） |
+|---------|-------------------|
+| 宿主抽象层重构（`hosts/` 目录） | 重写完整的 Python CLI（spec-kit 的 specify 命令） |
+| 模板系统优先级栈（`skills/`、`templates/`） | 社区扩展市场与目录系统（catalog.community.json） |
+| 工作流引擎最小 viable 实现（支持 gxpm phase） | 30+ 宿主的手写适配文件（用代码生成替代） |
+| SDD 宪法与 artifact 合同融合 | 文件系统状态机的服务端化/协作化 |
+| `*.tmpl` 多宿主渲染管道 | 扩展 ZIP 下载与版本兼容检查（复用现有包管理器） |
+
+### 1.3 成功标准
+
+1. 新增宿主时仅需修改/新增一个声明文件（类似 spec-kit 的集成子包），无需改动核心代码
+2. skill 模板支持四层覆盖：项目本地 `.gxpm/local/` > 预设 > 扩展 > 核心 `skills/`
+3. gxpm phase 推进可由 YAML 工作流定义驱动，支持暂停/恢复/人工 gate
+4. 所有变更不破坏现有 `.gxpm/issues/` 状态机和 `bun test` 测试集
+
+---
+
+## 二、架构约束总览
+
+### 2.1 从 spec-kit 继承的约束（必须遵守）
+
+| 约束 | 说明 | gxpm 应对策略 |
+|------|------|--------------|
+| **模板运行时解析栈** | Override > Preset > Extension > Core 优先级不可绕过 | `TemplateResolver` 类严格按栈解析，单元测试覆盖优先级冲突 |
+| **命令命名空间隔离** | 扩展命令必须遵循 `gxpm.{ext-id}.{cmd}`，不可 shadow core | `CapabilityRegistry` 注册时校验命名空间前缀 |
+| **宿主 CLI Key 匹配** | `requires_cli=True` 时 `key` 必须等于可执行文件名 | `HostAdapter` 抽象中保留 `detect()` 方法，使用 `which` 语义 |
+| **上下文文件标记** | 使用显式 START/END 标记管理代理目录注入段 | 沿用现有 `<!-- BEGIN GXPM -->` / `<!-- END GXPM -->` 标记规范 |
+| **路径逃逸防护** | 所有文件写入必须校验目标路径在允许范围内 | 复用已有路径校验，提取为共享 `safe-path.ts` 工具 |
+| **SDD 宪法 Article I-IX** | Library-First、CLI Mandate、Test-First、Simplicity Gate 等 | 写入 `docs/governance/development-contract.md`，作为 skill 生成的前置检查 |
+
+### 2.2 从 spec-kit 规避的约束（主动打破）
+
+| 约束 | spec-kit 现状 | gxpm 规避策略 |
+|------|--------------|--------------|
+| **同步 I/O 架构** | 全同步阻塞，fan-out 无法并行 | 工作流引擎基于 async/await 构建，步骤可标记 `parallel: true` |
+| **单体 CLI 文件** | `__init__.py` 近 6,000 行 | 已是模块化 TypeScript，保持子命令按文件拆分 |
+| **无数据库/纯文件状态** | 状态以 JSON 文件落盘 | 保留文件状态机作为默认，但接口抽象允许未来接入 SQLite/KV |
+| **单项目隔离** | 产物严格落在 `.specify/` 下 | 支持用户级 `~/.gxpm/` 与项目级 `.gxpm/` 叠加 |
+| **手写 30+ 宿主适配** | 每宿主一个子包，重复性声明 | 采用"协议 schema + 代码生成"，宿主差异用 YAML 描述 |
+
+### 2.3 gxpm 自身新增约束
+
+| 约束 | 来源 | 说明 |
+|------|------|------|
+| **TypeScript 运行时** | 产品定位 | 所有核心引擎代码必须为 TypeScript，禁止引入 Python 运行时依赖 |
+| **gxpm issue 状态机兼容** | 现有契约 | 工作流引擎的 step ID 必须能映射到现有 phase（triage/plan/dispatch/…） |
+| **Commit 引用规范** | AGENTS.md | 任何代码改动必须关联 `GXPM-N` issue |
+| **Worktree 隔离** | `.gxpm/config.json` | 实现阶段默认使用 git worktree，工程变更需在独立 worktree 验证 |
+
+---
+
+## 三、阶段化实施路线
+
+### Phase 1：基础设施与约束层（预计 1 周）
+
+**目标**：建立模板解析栈、路径安全、SDD 契约检查的基础设施。
+
+**交付物**：
+1. `core/template-resolver.ts` — 四层优先级模板解析器
+   - 接口：`resolve(templateName: string, context: RenderContext): string`
+   - 优先级栈：`local/ > presets/<id>/ > extensions/<id>/ > skills/`
+   - 支持策略：`replace`（默认）、`prepend`、`append`、`wrap`
+2. `core/safe-path.ts` — 路径逃逸防护工具
+   - 提取现有路径校验逻辑，统一为 `ensureInside(target: string, allowedRoot: string): void`
+   - 替换 `agents.ts`、`extensions.ts`（如有）中的内联校验
+3. `core/sdd-gate.ts` — SDD 宪法前置检查
+   - 实现 Nine Articles 的自动化检查（如：检测模块数是否超过 Simplicity Gate 阈值）
+   - 在 `bun run check` 中新增 `sdd-check` 子任务
+4. `docs/governance/development-contract.md` 更新
+   - 新增"规格驱动开发"章节，融入 Nine Articles
+
+**验收标准**：
+- `bun test` 新增 `template-resolver.test.ts`、`safe-path.test.ts`、`sdd-gate.test.ts`，全部通过
+- `bun run check` 包含 sdd-check 且无报错
+- 现有技能生成不受破坏（`bun run gen:skill-docs` 输出一致）
+
+**架构约束检查点**：
+- [ ] 模板解析栈优先级不可被配置绕过（硬编码为常量）
+- [ ] 路径校验覆盖所有文件写入路径（grep `_ensure_inside\|writeFile\|mkdir` 全命中）
+
+---
+
+### Phase 2：宿主抽象注册表（预计 1 周）
+
+**目标**：将 `hosts/claude.ts`、`hosts/codex.ts` 等硬编码适配重构为注册表驱动的声明式系统。
+
+**交付物**：
+1. `hosts/registry.ts` — 宿主适配注册表
+   - `HostAdapter` 接口：`key`、`name`、`detect(): boolean`、`install(command: CommandDef, path: string): void`、`uninstall(commandName: string): void`
+   - `HOST_REGISTRY: Map<string, HostAdapter>`
+   - 注册函数：`registerHost(adapter: HostAdapter)`
+2. `hosts/adapters/` 目录
+   - `claude.ts`：Claude Code 适配（Markdown 命令格式）
+   - `codex.ts`：Codex CLI 适配（Skills 格式）
+   - `cursor.ts`：Cursor 适配（.cursorrules / 命令格式）
+   - `kimi.ts`：Kimi Code CLI 适配（Skills 格式）
+   - 每文件 <100 行，仅含适配元数据与格式转换函数
+3. `hosts/schema.ts` — 宿主协议 schema
+   - 定义 `CommandDef`、`HostConfig`、`OutputFormat` 类型
+   - 支持四种格式：markdown、toml、yaml、skills
+4. `scripts/gen-host-adapters.ts` — 宿主适配代码生成器（可选，MVP 阶段可手写）
+   - 输入：`hosts/adapters/<name>.yaml` 描述文件
+   - 输出：`hosts/adapters/<name>.ts` 适配代码
+
+**验收标准**：
+- `bun test` 新增 `hosts/registry.test.ts`，验证注册/卸载/检测逻辑
+- 现有 `gxpm init` 对 Claude/Codex/Cursor 的初始化行为保持不变（黑盒兼容）
+- 新增宿主适配时，仅需新增一个 `<50 行` 的适配文件并在 `hosts/index.ts` 导入
+
+**架构约束检查点**：
+- [ ] `requires_cli=true` 的宿主 `key` 与可执行文件名匹配（`detect()` 使用 `which` 语义）
+- [ ] 宿主命令安装使用显式 START/END 标记
+- [ ] 命令命名空间隔离：宿主级命令前缀为 `/gxpm`，扩展级为 `/gxpm.{ext-id}.{cmd}`
+
+---
+
+### Phase 3：声明式工作流引擎（预计 2 周）
+
+**目标**：将 gxpm phase gate 从硬编码 TypeScript 逻辑升级为 YAML 声明式工作流，支持暂停/恢复/人工 gate。
+
+**交付物**：
+1. `core/workflows/` 目录（自治子系统，不依赖扩展/预设逻辑）
+   - `engine.ts`：`WorkflowEngine` — 加载、校验、执行、持久化、恢复
+   - `definition.ts`：`WorkflowDefinition` — YAML 解析与 schema 校验
+   - `state.ts`：`RunState` — 每步后保存到 `.gxpm/workflows/runs/{run_id}/state.json`
+   - `context.ts`：`StepContext` — 传递 inputs、steps 结果、变量
+2. `core/workflows/steps/` — 内置步骤类型（最小 viable 集）
+   - `command.ts` — 调用 gxpm CLI 子命令
+   - `shell.ts` — 执行 shell 命令
+   - `gate.ts` — 交互式人工审核（阻塞，等待用户输入 y/n）
+   - `if_then.ts` — 条件分支
+   - `fan_out.ts` / `fan_in.ts` — 集合分发与结果聚合
+   - 每步骤继承 `StepBase`，含 `execute()`、`validate()`、`canResume()`
+3. `workflows/gxpm-standard.yml` — gxpm 标准工作流定义
+   - 将现有 phase gate 映射为步骤序列：`triage → plan → dispatch → implement → verify → qa → land`
+   - 每个 phase 对应一个 `command` 步骤：`gxpm issue transition {id} {phase}`
+   - `gate` 步骤用于 phase 间的人工确认点
+4. `core/workflows/expressions.ts` — Jinja2-like 表达式引擎
+   - 最小实现：变量插值 `${var}`、条件表达式 `{% if %}`
+   - 上下文：inputs、steps 输出、环境变量
+
+**状态机定义**：
+
+```yaml
+schema_version: "1.0"
+id: gxpm-standard
+name: "GXPM Standard Delivery Workflow"
+inputs:
+  issue_id: string
+  auto_land: boolean
+steps:
+  - id: triage
+    type: command
+    config: { command: "gxpm issue transition ${issue_id} triage" }
+  - id: plan_gate
+    type: gate
+    config: { prompt: "计划已就绪，确认进入 dispatch？" }
+  - id: dispatch
+    type: command
+    config: { command: "gxpm issue transition ${issue_id} dispatch" }
+  - id: implement
+    type: command
+    config: { command: "gxpm issue transition ${issue_id} implement" }
+  - id: verify
+    type: command
+    config: { command: "gxpm issue transition ${issue_id} verify" }
+  - id: qa_gate
+    type: gate
+    config: { prompt: "QA 通过，确认进入 land？" }
+  - id: land
+    type: command
+    config: { command: "gxpm issue transition ${issue_id} land" }
+```
+
+**验收标准**：
+- `bun test` 新增 `workflows/engine.test.ts`，覆盖：
+  - 工作流加载与校验
+  - 顺序执行与状态持久化
+  - gate 步骤暂停与 resume
+  - if 条件分支
+  - fan-out/fan-in 集合处理
+- 现有 `gxpm issue transition` CLI 行为不变
+- 工作流运行状态文件 `.gxpm/workflows/runs/{id}/state.json` 可被独立读取恢复
+
+**架构约束检查点**：
+- [ ] 步骤 ID 唯一性校验（禁止 `:` 字符）
+- [ ] schema_version 严格校验（仅支持 `1.0`，未来升级需显式迁移）
+- [ ] Resume 粒度：顶层步骤索引级（与 spec-kit 保持一致，嵌套 resume 标记为 Phase 4 增强）
+- [ ] 工作流引擎不依赖扩展/预设子系统（模块边界清晰）
+
+---
+
+### Phase 4：SDD 宪法与 Artifact 合同融合（预计 1 周）
+
+**目标**：将 Spec Kit 的 SDD 方法论嵌入 gxpm artifact 体系，使规格说明成为可执行的主要产物。
+
+**交付物**：
+1. `docs/governance/spec-driven-contract.md` — SDD 执行合同
+   - 定义规格（spec）、计划（plan）、任务（tasks）三种 artifact 的标准结构
+   - 映射到 gxpm 现有 artifact 类型：`triage-report` → spec，`implementation-plan` → plan，`task-list` → tasks
+   - 定义 Phase -1 Gates（开发前必须通过的检查清单）
+2. `templates/spec-template.md.tmpl` — 规格模板
+   - 需求澄清、范围界定、非目标、成功标准、验收条件
+3. `templates/plan-template.md.tmpl` — 计划模板
+   - 架构决策、风险评估、阶段划分、验证方法
+4. `templates/tasks-template.md.tmpl` — 任务模板
+   - 垂直切片、独立可抓取、验收标准
+5. `core/artifact-validator.ts` — Artifact 结构校验器
+   - 校验 spec/plan/tasks 的必要 frontmatter 和章节
+   - 在 `gxpm artifact write` 时自动触发
+
+**验收标准**：
+- `bun test` 新增 `artifact-validator.test.ts`
+- `gxpm issue create --auto-id` 时，若 type 为 feature，自动提示生成 spec artifact
+- 现有 artifact 类型不破坏，新增 spec/plan/tasks 为可选增强
+
+**架构约束检查点**：
+- [ ] Simplicity Gate：单个 feature 的 spec + plan + tasks 不超过 3 个 artifact 文件
+- [ ] Test-First：plan artifact 必须包含测试策略章节
+- [ ] Explicit over Implicit：所有假设和依赖必须显式声明
+
+---
+
+### Phase 5：整合与验收（预计 1 周）
+
+**目标**：将前四阶段成果整合为完整用户流程，端到端验证。
+
+**交付物**：
+1. `gxpm workflow` 子命令
+   - `gxpm workflow list` — 列出可用工作流
+   - `gxpm workflow run <workflow-id> --issue <id>` — 运行工作流
+   - `gxpm workflow status <run-id>` — 查看运行状态
+   - `gxpm workflow resume <run-id>` — 恢复暂停的工作流
+2. `gxpm init` 升级
+   - 初始化时检测宿主并注册对应适配器
+   - 安装标准工作流定义到 `.gxpm/workflows/`
+3. 端到端测试（E2E）
+   - 模拟完整 issue 生命周期：create → triage → plan → dispatch → implement → land
+   - 验证工作流状态机与 `.gxpm/issues/` 状态机的一致性
+
+**验收标准**：
+- `bun test` 全量通过（现有 + 新增）
+- `bun run check` 通过
+- E2E 测试脚本在独立 worktree 中运行成功
+- 新增代码行数不超过 3,000 行（Simplicity Gate）
+
+---
+
+## 四、风险与缓解
+
+| 风险 | 可能性 | 影响 | 缓解措施 |
+|------|--------|------|---------|
+| **工作流引擎过度设计** | 中 | 高 | Phase 3 严格限制为最小 viable 步骤集（5 种），禁止引入循环/并发等复杂特性 |
+| **宿主适配破坏现有初始化** | 中 | 高 | Phase 2 保持黑盒兼容，新增适配文件后运行现有 `hosts/*.test.ts` 全量回归 |
+| **模板解析栈引入性能退化** | 低 | 中 | 解析结果缓存到 `.gxpm/cache/templates.json`，缓存键为 `templateName + priorityStackHash` |
+| **SDD 宪法与现有流程冲突** | 中 | 中 | Phase 4 的 spec/plan/tasks 为可选增强，不强制替换现有 triage-report/implementation-plan |
+| **Commit 规模失控** | 低 | 高 | 每 Phase 独立分支（`gxpm-N-sdd-phase-{1-5}`），单 PR 不超过 400 行变更 |
+
+---
+
+## 五、验证方法
+
+1. **单元测试**：每阶段新增测试文件，覆盖率目标 >80%
+2. **回归测试**：`bun test` 全量通过，现有测试零破坏
+3. **集成测试**：在独立 worktree 中运行 `gxpm init` + `gxpm workflow run` 完整流程
+4. **静态检查**：`bun run check` 通过（类型检查 + lint）
+5. **架构约束检查**：每阶段结束时运行自定义脚本验证约束检查点
+6. **代码规模检查**：`find src/core/workflows -name '*.ts' | xargs wc -l` 确认引擎代码 <1,500 行
+
+---
+
+## 六、附录：与 gxpm 现有能力的整合矩阵
+
+| gxpm 现有能力 | 本计划增强点 | 文件映射 |
+|--------------|-------------|---------|
+| `skills/gxpm/SKILL.md` | 引入 SDD 宪法章节 | `templates/spec-template.md.tmpl` |
+| `hosts/claude.ts` | 重构为 `hosts/adapters/claude.ts` | `hosts/registry.ts` |
+| `core/config.ts` | 增加模板解析配置 | `core/template-resolver.ts` |
+| `core/dag-executor.ts` | 工作流引擎可复用 DAG 执行经验 | `core/workflows/engine.ts` |
+| `.gxpm/issues/<id>/` | 工作流 run state 并存于 `.gxpm/workflows/runs/` | `core/workflows/state.ts` |
+| `bun run gen:skill-docs` | 支持 `--host all` 批量生成 | `hosts/registry.ts` 遍历注册表 |
+
+---
+
+*本计划遵循 gxpm 开发契约：任何代码改动开始前，确认有对应 GXPM-N issue 处于 dispatch/implement 阶段。*

package/docs/research/agents-md-best-practices.md

@@ -0,0 +1,207 @@
+# 好的 AGENTS.md 等于免费换模型，写错了比没文档更糟
+
+> **作者：** 老金 (@freeman1266)  
+> **来源：** https://x.com/freeman1266/status/2053055657335832828  
+> **发布时间：** 2026-05-09 03:13  
+> **互动数据：** 4 回复, 9 转发, 52 点赞, 82 收藏, 4,108 浏览
+
+---
+
+一份文件，让 AI 编码质量从 Haiku 跳到 Opus——或者让它比裸跑还烂。
+
+下面这套东西，是 Augment Code 团队从一个大型 monorepo 里抽出几十份真实的 AGENTS.md 跑出来的实测结论，外加老金我自己的怀疑视角，把里面的几个坑也补上去。
+
+希望读完这一篇，你不再"凭感觉"写 AGENTS.md。
+
+---
+
+## 让工程师惊掉下巴的实验
+
+Augment Code 做了件事：从一个大型 monorepo 里提取了数十个 AGENTS.md，逐一测量它们对 AI 代码生成质量的影响。
+
+结果他们自己都没想到——
+
+- **最好的 AGENTS.md**，带来的质量提升相当于把模型从 Claude Haiku 直接换成 Claude Opus。
+- **最差的 AGENTS.md**，让输出比完全不写任何文档还糟。
+- 更夸张的是：同一份 AGENTS.md，在常规 bug 修复任务上把代码质量提升了 25%，在同一模块的复杂功能任务上却让完整性下降了 30%。
+
+**一份文件，正负 30% 的波动。**
+
+> **泼冷水：** "Haiku 跳到 Opus"是个非常抓人的比喻，但严格说不是模型变聪明了。好 AGENTS.md 提升的是"消除歧义"的能力，不是模型自身的推理能力。遇到真正需要多步逻辑推演的架构难题，再好的文档也救不了 Haiku。把它当成"减少 Agent 在你代码库里走错路的概率"更准确。
+
+把这件事讲清楚，是因为后面的所有模式，本质都在做一件事：**给 Agent 一份没有歧义的执行手册。**
+
+---
+
+## 7 个有效模式
+
+### 1. 渐进式披露，而不是把所有东西塞进一个文件
+
+把 AGENTS.md 想成一个**入口**，不是百科全书。
+
+- 主文件控制在 **100~150 行**，覆盖常见场景与工作流
+- 细节推到几份"按需加载"的参考文件里
+
+**实验数据：** 在一个约 100 个核心文件的中等规模模块里，这个体量的主文件让所有指标提升 10~15%。一旦超过 150 行，收益开始反向。
+
+> **为什么是 150 行？** 因为当前 AI 编码助手普遍存在"中间迷失"（Lost in the Middle）现象——即便模型宣称 200K 甚至 1M 上下文，当规则被埋在长文本中段时，遵循率会直线下降。150 行是把注意力机制压在"高度聚焦区"的甜区。
+
+---
+
+### 2. 程序性工作流：让 Agent 从"无法完成"到"一次成功"
+
+把任务写成**编号的多步骤工作流**，是测量到的最强模式之一。
+
+一个真实例子：部署新集成的六步工作流。Agent 照步骤执行后——
+
+- 缺少连接文件的 PR 比例：**40% → 10%**
+- 正确性 **+25%**
+- 完整性 **+20%**
+
+**工作流的本质是消除歧义，让 Agent 不用猜。**
+
+---
+
+### 3. 决策表：在写第一行代码前就解决"二选一"
+
+代码库里经常有两三种都说得通的做法——React Query 还是 Zustand？REST 还是 GraphQL？
+
+决策表**强制提前选好**。Agent 读完就知道走哪条路，不用在代码里反复试探。
+
+**效果：** 相关区域的 PR 在"最佳实践遵从度"上 **+25%**。
+
+---
+
+### 4. 真实代码片段，不是伪代码
+
+来自实际生产代码的 **3~10 行短片段**，改善了代码复用和模式遵从。
+
+关键词是"**真实**"——伪代码和示意性代码效果远不如直接从生产代码里截取的。但保持在最相关的几个示例以内，超过这个数量，Agent 会开始在错误的地方做模式匹配。
+
+> **担心代码过时？** 动态引用优于硬编码。如果工具支持，尽量用相对路径或 @ 引用核心文件，让 Agent 跳去看活的代码；只有在那段逻辑足够稳定时，才直接复制片段。复制进来的片段，必须进 Code Review 的 checklist——API 一变就同步更新，否则它就从资产变成毒药。
+
+---
+
+### 5. 每个"不要做"都配上"要做"
+
+只有警告的文档，表现一贯不如"**禁令 + 替代方案**"配对的文档。
+
+```
+❌ 不要直接实例化 HTTP 客户端
+
+✅ 不要直接实例化 HTTP 客户端。
+   使用 lib/http 中带有重试中间件的共享 apiClient。
+```
+
+第一条让 Agent 变得谨慎和探索性——它知道不能做什么，但不知道该做什么，于是开始翻代码库。第二条告诉它该怎么做，直接继续。
+
+有 15 条以上连续"不要做"且没有"要做"的文件，会导致 Agent **过度探索、保守行事、完成更少工作**。
+
+---
+
+### 6. 代码模块化，文档也要模块化
+
+表现最好的 AGENTS.md，描述的是**相对隔离的子模块**。仓库根目录的大型跨领域文件，效果不如模块级别的。
+
+更关键的是：**AGENTS.md 只是入口，周围环境才是问题所在。**
+
+实验里，一个模块有 37 个相关文档总计 50 万字符；另一个有 226 个文档超过 2MB。这两种情况下，仅仅移除 AGENTS.md 几乎不改变 Agent 的行为——因为 Agent 会继续找到并阅读周围的文档蔓延。
+
+**一个聚焦的 150 行 AGENTS.md，放在 50 万字符的周围规格之上，救不了你。**
+
+> **修复文档环境，不是只修入口。**
+
+---
+
+### 7. 特定领域规则要具体、可执行
+
+语言特性、框架约定、安全限制——这些规则有效，前提是**具体且可执行**。堆几十条模糊规则，效果跟没写一样。
+
+---
+
+## 两个最常见的失败模式
+
+### 1. 过度探索陷阱（上下文腐烂）
+
+最常见的失败，本质是**上下文中毒**。
+
+两种写法触发它：
+
+**太多架构概述**  
+Agent 被拉去阅读数十个文档，试图"更好地理解架构"，加载几万甚至几十万 token 后，输出反而变差。
+
+**过多警告堆叠**  
+大量"不要做"且没匹配"要做"，Agent 会对每一条警告都去验证当前方案是否违规。30~50 条警告，意味着它要去翻迁移脚本、检查 API 版本兼容性、探索认证中间件——即使这些跟当前任务完全无关。
+
+### 2. 文档描述了代码库里还不存在的模式
+
+如果在 AGENTS.md 里写了一个"打算引入但还没落地"的新模式，Agent 会被积极地引向错误方向——它按文档去找根本不存在的代码，然后产生错误的解决方案。
+
+> **AGENTS.md 描述现状，不是愿景。**
+
+---
+
+## 文档发现率
+
+Augment Code 在数百个 session 里追踪了 Agent 实际读取了什么：
+
+| 文档类型 | 发现率 |
+|---------|--------|
+| AGENTS.md | **100%**，自动发现 |
+| AGENTS.md 中引用的参考文件 | **>90%**，按需加载 |
+| 当前工作目录的 README.md | **>80%** |
+| 嵌套子目录的 README | **~40%** |
+| _docs/ 文件夹中无引用的孤立文档 | **<10%** |
+
+一个服务在 _docs/ 里放了 3 万字符的协议设计、限流规则和安全文档，Agent 在数十个 session 里几乎从未打开过其中大多数。
+
+> **AGENTS.md 是唯一具有可靠发现性的文档位置。** 如果某些内容需要被 Agent 看到，要么在那里，要么从那里直接引用。把内容移到被引用的位置，往往比写更多文档更有杠杆效果。
+
+---
+
+## 几个值得讨论的边界
+
+### 1. AGENTS.md 不是 README 的替代品
+
+读到"主文件控制在 150 行 / 不要写架构概述"，很多人会担心：那新人入职怎么办？架构图、历史决策、设计哲学谁来讲？
+
+**答案是分受众。**
+
+- **README 是写给人类的** — 人类需要架构、愿景、来龙去脉，才能在脑子里建立心智模型。
+- **AGENTS.md 是写给机器的执行手册** — 它只关心规则、工作流、防坑指南。
+
+接受这种分离，是 AI 时代工程实践的第一步。两份文件不是 DRY 的破坏，而是因为受众不同，关心的层级也不同。当然，两份都要维护——这是真实成本，要计入。
+
+### 2. 维护成本不能假装不存在
+
+"使用真实代码片段"+"描述现状不描述愿景"这两条加起来，意味着 AGENTS.md 是一份**高频更新文档**。
+
+不接受这一点的团队，AGENTS.md 几个月后就会变成第二种失败模式——描述了代码库里已经不存在的模式，把 Agent 主动引向错误方向。
+
+**应对办法：**
+
+- **优先用引用，不用复制** — 真实代码片段尽量是文件路径 + 函数名而不是粘贴。
+- **复制片段进 Code Review checklist** — API 改动时强制 reviewer 检查 AGENTS.md。
+- **定期 prune** — 每个迭代/季度删一遍过时的警告与工作流，比加新条目更重要。
+
+### 3. 150 行不是真理，是当前模型的甜区
+
+这条数据来自 Augment Code 自家的 RAG 与上下文管理策略。换一套底层 Agent（Cursor / Claude Code / Devin / Copilot Workspace），检索算法和注意力分布都会不同。
+
+100~150 行真正的含义不是"上限"，而是：**把规则压进模型注意力机制最聚焦的那一段。**
+
+模型一升级，这个数字会往上挪；但"主文件聚焦、细节外推"这个结构原则不会变。
+
+> **把它当原则用，不要当数字背。**
+
+---
+
+## 最后
+
+这件事最有价值的地方，不是抛出了什么新奇的结论，而是用数据把一件模糊的事说清楚了：
+
+**AGENTS.md 不是越多越好，不是越全越好，不是越详细越好。**
+
+它是一个**精心设计的上下文入口**。写好了，相当于免费升级了一个更强的模型；写烂了，你付出维护成本，换来一个比裸跑更差的 AI。
+
+在 AI 工程里，"少即是多"这句话，从未像现在这样字面成立过。