从不提出更简单的做法
Never proposed the simpler way
智能体交出一个能用、但过度复杂又啰嗦的方案。它很少会说“改小一点就够了”“这个不需要”或者“这个改动根本不该做”。
适用于: Claude Code · Cursor · Codex · Copilot agent
症状
绕来绕去的控制流、多余的层次、几行就能搞定的地方写了长篇注释。人类审查者反复留下同一条意见:“有更简单的办法”,按他们说的改完,diff 会缩小很多。
为什么会这样
在 Thorsten Ball 的 PR 帖下,@lawrjones 说他合并的 PR 里有 40% 需要他出手调整代码,多半是架构选择问题,或者明明有更简单的路 Opus 却没看到、把代码写复杂了。@akepka_:即使是前沿模型,也“很少会告诉你某样东西不需要,或者可以简单 10 倍”。@isaacvando 经常要求关掉 PR,或用更符合项目的方式重做,他说 Codex 从来不会建议关掉 PR。@LucaColonnello 常看到“绕远路的笨办法”,也缺少对“为什么需要这个”的追问。@clintwinter13 常抓到“过于啰嗦的代码和糟糕的设计”;@benjaminhonorio 抓到过过度复杂或根本不必要的代码;@GrmlBob 发现大项目里 Opus 的代码严重臃肿;@motziabuelnasr 审查的智能体 PR 有的难以理解或无法扩展;@zeenix 觉得 AI 生成的文档和注释人根本读不懂。智能体照单实现需求,而对需求的规模或必要性提出异议,很少得到奖励。
示例
示意。
ts// Asked: show the user's display name, falling back to their email
class DisplayNameResolverFactory {
create(strategy: "name" | "email" = "name") { return new DisplayNameResolver(strategy); }
}
// ...60 more lines...
// Simpler:
const displayName = user.name || user.email;
复制即用的修复
按你用的智能体挑选文件。规则片段用英文写,放进任何仓库都能用。
Claude Code:加入 CLAUDE.md
CLAUDE.md## Propose the smallest change first
- Before writing code, state the smallest change that would satisfy the request. Implement that
unless the user asks for more.
- If you believe the request isn't needed, or a much simpler approach exists (including reusing
existing code or not making the change), say so first and let the user choose.
- No new classes, layers, factories or config options unless the request needs them.
- Comments explain why, briefly. Don't narrate what the code does.
- In your summary, name one thing you chose not to build and why.
Codex、Copilot 编码智能体等:加入 AGENTS.md
AGENTS.md## Propose the smallest change first
- Before writing code, state the smallest change that would satisfy the request. Implement that
unless the user asks for more.
- If you believe the request isn't needed, or a much simpler approach exists (including reusing
existing code or not making the change), say so first and let the user choose.
- No new classes, layers, factories or config options unless the request needs them.
- Comments explain why, briefly. Don't narrate what the code does.
- In your summary, name one thing you chose not to build and why.
Cursor:项目规则
.cursor/rules/never-proposed-the-simpler-way.mdc---
description: "AgentFails: Never proposed the simpler way"
alwaysApply: true
---
## Propose the smallest change first
- Before writing code, state the smallest change that would satisfy the request. Implement that
unless the user asks for more.
- If you believe the request isn't needed, or a much simpler approach exists (including reusing
existing code or not making the change), say so first and let the user choose.
- No new classes, layers, factories or config options unless the request needs them.
- Comments explain why, briefly. Don't narrate what the code does.
- In your summary, name one thing you chose not to build and why.
Diff 预算检查(提交前或在 CI 中运行)
改编自 dev.to(yureki_lab)的 diff budget 文章。读取真实的 git diff,所以通过 shell 做的修改也逃不掉。用法:python3 scripts/diff_budget.py origin/main 6 150
scripts/diff_budget.py#!/usr/bin/env python3
"""Fail if the diff vs BASE touches files outside .agent-scope or exceeds the budget."""
import fnmatch, os, subprocess, sys
base = sys.argv[1] if len(sys.argv) > 1 else "HEAD"
max_files = int(sys.argv[2]) if len(sys.argv) > 2 else 6
max_lines = int(sys.argv[3]) if len(sys.argv) > 3 else 150
allowed = []
if os.path.exists(".agent-scope"):
allowed = [l.strip() for l in open(".agent-scope") if l.strip() and not l.startswith("#")]
out = subprocess.run(["git", "diff", "--numstat", base], capture_output=True, text=True, check=True).stdout
untracked = subprocess.run(["git", "ls-files", "--others", "--exclude-standard"],
capture_output=True, text=True, check=True).stdout.split()
files, lines, outside = 0, 0, []
rows = [r.split("\t") for r in out.strip().splitlines()] + [["0", "0", p] for p in untracked]
for added, deleted, path in rows:
files += 1
if added != "-":
lines += int(added) + int(deleted)
if allowed and not any(fnmatch.fnmatch(path, p) for p in allowed):
outside.append(path)
problems = []
if outside:
problems.append("out-of-scope files: " + ", ".join(outside))
if files > max_files:
problems.append(f"{files} files changed (budget {max_files})")
if lines > max_lines:
problems.append(f"{lines} lines changed (budget {max_lines})")
if problems:
print("OVER BUDGET: " + "; ".join(problems))
sys.exit(1)
print(f"within budget: {files} files, {lines} lines")
全新上下文的审查技能(子智能体只看 diff,不看聊天记录)
沿用 Anthropic 代码审查文章里的做法:先验证,再让一个上下文干净的子智能体审 diff。命名为 review-diff,避免和内置或流行的 /code-review 技能重名。
.claude/skills/review-diff/SKILL.md---
name: review-diff
description: Review the current diff with fresh context before a PR. Use after /verify passes.
---
# Review the diff
Start a subagent that has NOT seen this conversation. Give it only:
- the original request (one paragraph, verbatim),
- the output of `git diff origin/main...HEAD`,
- the names of the test/build commands.
Ask it to report, with file:line for each finding:
1. **Wrong feature**: does the diff do what the request asked? Quote the request line each change serves.
2. **Bugs**: logic errors, missing edge cases (empty, null, boundary), unhandled errors,
unawaited promises, invented APIs or packages, swallowed exceptions.
3. **Overreach**: changes no request line needs (refactors, renames, formatting, dependency or
config edits, public API changes, weakened tests).
4. **Evidence gaps**: claims in the PR description that no command output supports.
Then fix real findings, or list them under "Known issues" in the PR. Do not argue with the reviewer
in the PR text; either fix or explain in one line.
来源与致谢
- @lawrjones on X: human steering in 40% of merged PRs, often over-complication
- @akepka_ on X: models rarely say something isn't needed or could be 10 times simpler
- @isaacvando on X: "Codex never says we should close the PR"
- @LucaColonnello on X: silly roundabout ways, no questioning why something is needed
- @clintwinter13 on X: overly verbose code and bad design
- @benjaminhonorio on X: overcomplicated or unnecessary code
- @GrmlBob on X: Opus code badly bloated on big projects
- @motziabuelnasr on X: agent PRs complex to reason about or not scalable
- @zeenix on X: AI-generated docs and comments gibberish to humans
- @thorstenball on X: "Why are you still using pull requests?" (the thread)