/agentsop-repo-state-gating

name: agentsop-repo-state-gating
version: 0.1.0
description: >-
  A 5-minute gate the coder runs at project kickoff (and again whenever the repo shape
  changes). Classifies the workspace into Greenfield / Brownfield-large / Mid-size-familiar
  / Library-SDK, then maps the state to an agent strategy (autonomy, context primitive, tool
  choice). Use BEFORE picking Cursor vs Claude Code vs Aider, BEFORE turning on repo-map,
  BEFORE writing the first prompt. Skip only if the same repo was gated within the last day
  and nothing changed. Search keywords: greenfield vs brownfield, new project vs existing
  codebase, project setup strategy, legacy codebase agent, where to start a coding agent.
domain: coder-agent meta-strategy
audience: coder-agents (Claude Code / Cline / Cursor / Aider) and the humans driving them
source: aider-sop R4, dify-sop A6 escape-hatch, dspy-sop M3 compile-gate, BMAD greenfield/brownfield, GSD codebase-map, The Brownfield Problem (jjmasse 2026)

Repo-State Gating — 5-Line Decision at Project Kickoff

> 一句话：**agent strategy = f(repo-state)**。先判定 repo 状态，再选工具/上下文原语/自治程度。 > 跳过这一步 = 用错工具，浪费一个小时的上下文。

---

1. 何时激活

只在以下时刻跑一次（≤5 分钟）：

• **新会话第一次进入某仓库**（含 `cd` 切到新目录、`git clone` 后第一次启动 agent）
• **仓库形态显著变化**：从空目录跑到 100+ 文件、引入新子系统、merge 一个大 PR
• **agent 选错过工具**之后的复盘（"我为什么开了 Cursor 写 SDK / 用 Aider 起新项目"）
• **被项目经理/同事问到** "你应该用 X 还是 Y" — 给一个 5 行的答复

**不要激活**：

• 同一 repo 当天已经 gate 过 → 复用上一次结论
• 单次脚本性任务（"帮我跑个一次性的数据迁移"） → 跳过，直接干
• 你已经知道答案且仓库状态明显（"这是个三天前刚 `npx create-next-app` 的仓库"） → 仍写下结论，但 30 秒搞定

---

2. 核心心智模型

2.1 一句话

> **不同 repo 状态，agent 的最佳武器不同**。同一个 prompt 在 greenfield 里能跑通，在 brownfield 里会胡编路径；同一个 Aider 在 brownfield 里发光，在 greenfield 里失去 70% 价值。

2.2 四个状态 × 四个杠杆

状态                  | 关键约束          | 最大杠杆            | 风险
----------------------+-------------------+---------------------+-------------------
Greenfield            | 没有现成符号      | LM 自治 + scaffolder| 过度设计、目录漂移
Brownfield-large      | 上下文炸 + 风格僵 | repo-map + 严格 /add| 修错文件、违反约定
Mid-size-familiar     | 你脑里有图        | 最小上下文 + /ask   | 多加文件稀释信号
Library / SDK         | 你的代码即 API    | 约定 + test-fix 环  | 破坏向后兼容

四个杠杆（按优先级递减）：

1. **上下文原语**：repo-map / scaffolder / docstrings / test runner 2. **自治程度**：full-auto / approve-each-tool / ask-then-code / pair 3. **工具选择**：Claude Code / Cursor / Aider / Cline 4. **范围纪律**：/add 数量、token 预算上限、是否允许 free-roam

2.3 错误状态假设的代价

| 假设错 | 症状 | 损失 | |---|---|---| | 把 brownfield 当 greenfield | LM 编造路径、违反隐含约定、改错文件 | 1–3 小时回滚 + 信任度 | | 把 greenfield 当 brownfield | 等不到 repo-map 帮忙（图是空的）、纠结要不要 /add | 启动成本 + 错失 scaffolder | | 把 library 当一般 brownfield | 改了公共 API 没改 changelog、破坏外部用户 | 隐性 bug，回归测试才能发现 | | 把 mid-size-familiar 当 brownfield-large | 过度加载文件 / 反复扫 repo-map / token 爆 | 浪费的不是错误，而是 *慢* |

> 引用：Aider 自己声明，"For 'build me a new project from scratch' the repo-map is empty and the safety guarantees provide no marginal value." [aider-sop-skill/references/R4-anti-patterns.md §1] > 引用：The General Partnership (2026)："legacy code doesn't come in neat, modular pieces… AI agent must learn the project's established patterns and not break things." [thegeneralpartnership.substack.com/p/a-practical-guide-to-brownfield-ai]

---

3. SOP 工作流（5 步，每步 ≤30 秒）

Step 1 — 三个一次性命令

git log --oneline | wc -l          # 提交数
git ls-files | wc -l               # 跟踪文件数
ls -la                              # 顶层结构（package.json? pyproject? README? src/?）

可选第四个：`git log --since='90 days ago' --oneline | wc -l`（活跃度）

Step 2 — 五题门禁（每题二选一）

| Q | 选 A | 选 B | |---|---|---| | 1. `git ls-files \| wc -l` | < 20 → A | ≥ 20 → B | | 2. 仓库里有公开/发布 API（PyPI、npm、SDK）？ | 否 → A | 是 → B | | 3. 你能不打开文件就说出主要模块名？ | 否 → A | 是 → B | | 4. 一次完整改动通常跨几个文件？ | 1–3 → A | 4+ → B | | 5. 风格约定写在哪？（CONVENTIONS.md / lint / package.json） | 没写过 → A | 有 → B |

Step 3 — 状态分类（看 A/B 计数 + 关键信号）

Q1=A 且 Q5=A                              → Greenfield
Q2=B（公共 API 存在）                       → Library / SDK
Q1=B 且 Q3=A（不熟）                       → Brownfield-large
Q1=B 且 Q3=B（熟）且 Q4=A                  → Mid-size-familiar
其他                                       → Brownfield-large 兜底（最保守）

Step 4 — 查状态卡片（§4 操作模型），挑工具 + 原语 + 自治度

Step 5 — 把结论写一行进 chat 或 README

[repo-state: brownfield-large] tool=Aider, primitive=repo-map, autonomy=approve-each,
add-budget=2-5 files (<25k tok), convention=CONVENTIONS.md required.

> 这一行让 *下一次会话* 也能秒接，省去重新 gate。

---

4. 操作模型（8 个 ops）

op-1  gate-classify
  trigger: 新会话进入仓库
  rule: 跑 §3 Step 1 三命令 + §3 Step 2 五题 → 输出四态之一

op-2  greenfield-strategy
  trigger: state=greenfield
  rule:
    - 工具: Claude Code / Cursor / 纯 LLM 对话；不要 Aider（repo-map 空）
    - 原语: scaffolder 优先（create-next-app, cargo new, uv init, cookiecutter）
    - 自治: 中-高；让 LM 一次产出多文件骨架
    - 范围: 不限；但每生成 ~10 文件就 commit 一次

op-3  brownfield-large-strategy
  trigger: state=brownfield-large
  rule:
    - 工具: Aider（repo-map 是核心杠杆） / Claude Code（长上下文兜底）
    - 原语: 符号索引 / repo-map / ctags / tree-sitter；先 /ask 再 /code
    - 自治: 低；每个 tool-call / 编辑都 approve
    - 范围: /add 严格控制在 2–5 文件 + <25k tokens [aider edit-errors troubleshooting]
    - 必读: CONVENTIONS.md（不存在就先建）

op-4  mid-size-familiar-strategy
  trigger: state=mid-size-familiar
  rule:
    - 工具: Aider --architect 或 Claude Code（你脑里有图，工具只是杠杆）
    - 原语: 你给定文件 + /read 约定文件；不浪费 repo-map 预算
    - 自治: 中；/ask 先讨论方案，/code 再动手
    - 范围: 1–3 文件，单次 commit

op-5  library-sdk-strategy
  trigger: state=library-sdk
  rule:
    - 工具: Aider --auto-test 或 Claude Code with test runner
    - 原语: test-fix 闭环最高价值；docstring 自动生成；semver 检查
    - 自治: 低；改公共 API 必须人工确认
    - 范围: 不只看本仓 — 同时看 CHANGELOG / migration guide
    - 必备: 写 CONVENTIONS.md（API 命名风格、错误模式、deprecation 节奏）

op-6  state-reclassify
  trigger: 跑了一周后仓库形态明显变了；或工具一直选错
  rule: 重跑 op-1；如状态升级（greenfield→brownfield）则把第一行结论改写

op-7  cross-repo-multi-state
  trigger: monorepo / 多包仓库
  rule:
    - 不跑整仓 gate，跑子目录 gate（cd packages/foo && 跑 op-1）
    - 不同子目录可以有不同状态；agent 进入子目录时切策略
    - Aider 用 --subtree-only；Claude Code 用