“跟着代码风格写”是诚实的建议，但你说不清那风格到底是什么，就写不出一致的代码。约定识别 Prompt 的作用是把”隐式”变成”显式”：哪些模式反复出现、哪些是例外、哪些只是三年前一次复制粘贴留下的 cargo-cult。如今 Claude Opus 4.7 和 Sonnet 4.6 都把 100 万 token 上下文做成了标配（截至 2026 年 6 月，一个窗口大约能容纳 5 万到 7.5 万行代码），agent 终于能采样到足够多的文件，分得清真正的约定和某个人的个人习惯。
TL;DR
- 跨主要目录采样 8-12 个文件，别只看 1-2 个。约定只有在足够的样本量下才会显现。
- 永远要求 Prompt 用
file:line把 outlier 列出来。离群点能告诉你团队主动排斥什么，或者还没来得及清理什么。 - 按优先级识别五件事：命名、分层、错误处理、测试、异步。命名和分层收益最大；注释风格和 import 顺序基本是噪声。
- 把结果写进团队真正在用的 agent 配置文件（
CLAUDE.md、AGENTS.md或.cursor/rules/），这样新的 AI 代码第一次就能贴合风格。 - 这是对 ESLint/Prettier 的补充，不是替代。lint 管机械规则，约定识别管结构决策。
适合哪些人
接手陌生代码库的工程师、进入新客户仓的外包，以及希望 agent 守家规、而不是每次会话都自己发明一套风格的工具构建者。
什么时候不建议用
20 文件以内的仓库就别用了。约定要有规模才算数，那么小直接全读更快。也别用识别去强推一个团队从没同意过的”约定”——Prompt 告诉你代码现在怎么写，不是它应该怎么写。
为什么上下文窗口的大小改变了这件事
早期的 agent 读不了几个文件窗口就满了，于是从极小的样本里过度归纳。截至 2026 年 6 月，这个限制基本消失了：
- Claude Opus 4.7 / Sonnet 4.6 把 100 万 token 上下文做成标配（无需 beta 标志、无额外加价），其中约 83 万 token 可用，相当于数千个源文件。
- Gemini 3.1 Pro 同样提供 100 万 token。
- ChatGPT（GPT-5.5） 在 Plus 套餐下的应用内上下文约 320 页；完整的 100 万窗口只在 $200 的 Pro 档开放。
窗口变大不等于”把整个 monorepo 粘进去”。更划算的做法是让 agent 先用 ripgrep（rg）把所有类型、函数、导出连同行号找出来，再只读周围上下文。这样既保证样本有代表性，又用前期几千 token 省下后面几万 token。Prompt 里要明确这么写。
输出应该放到哪
识别出来的约定，只有 agent 下次会话还能读到才有用。截至 2026 年 6 月，三个主流落点是：
| 目标文件 | 读取它的工具 | 说明 |
|---|---|---|
CLAUDE.md | Claude Code（仅 Anthropic 模型） | 分层：~/.claude/CLAUDE.md 全局、仓库根项目级、子目录级，加上被 gitignore 的 CLAUDE.local.md |
AGENTS.md | Codex、Cursor、Copilot、Gemini CLI、Aider、Windsurf、Zed | 开放标准（Linux 基金会，6 万+ 仓库）；纯 markdown，无强制结构 |
.cursor/rules/*.mdc | Cursor | 单条规则一个 .mdc 文件，按 glob 作用域生效，React 规则只在组件文件里加载 |
house-style 段落要写得精炼。模型每个上下文窗口大约能可靠遵循 150-200 条不同指令，而 Claude Code 自己的系统 Prompt 已经占掉约 50 条。一段 400 字、只有要点的风格块，胜过一篇没有 agent 读得完的 2000 字长文。
12 个可直接复制的 Prompt 模板
每个 Prompt 都假设 agent 能读仓库（Claude Code、Cursor、Codex CLI，或带文件访问权限的 IDE 助手）。凡是写”across the repo”的地方，让工具用 rg 去抓，而不是手动把文件塞进 Prompt。
1. house-style 检测扫描
Read 10 representative files from this repo (use ripgrep to pick files across the major directories, not just the entrypoint). Infer the house style across: (1) Naming (PascalCase / camelCase / snake_case per type), (2) File layout (one component per file? grouped helpers?), (3) Import sort, (4) Comment density, (5) Error pattern. Output as a "house-style.md" draft with file:line evidence for each claim.2. 命名规则
Scan exports across the repo. Classify naming conventions: (a) Components, (b) Hooks, (c) Utilities, (d) Constants, (e) Types / Interfaces, (f) Test files. Note exceptions. For each, output: convention + count + examples + outliers.3. 错误处理风格
Detect the error-handling convention: (1) Throw vs return tuple vs Result type, (2) Where errors get wrapped, (3) Error classes vs codes vs strings, (4) Where logging happens (caller vs callee). Output: dominant pattern + outliers (file:line).4. 分层 / 模块边界
Infer the layering: (1) Which folders are domain, which are infrastructure, which are UI? (2) Direction of imports - does UI import domain or domain import UI? (3) Any cyclic imports? (4) Cross-feature imports flagged. Output a directed graph in mermaid.5. 测试约定
Identify test conventions: (1) Co-located vs separate `tests/`? (2) Naming (`.test.ts` / `.spec.ts`)? (3) Mock strategy (jest.mock vs factory fakes), (4) Snapshot use, (5) Setup helpers shared or local. Output a one-page test style guide.6. DI 风格
How is DI handled in this repo? Options: constructor params, hooks/context, factory functions, framework container, none. Output: dominant pattern + examples + recommendation if mixed.7. 状态管理约定
Detect front-end state management: server state (react-query?), client state (zustand / redux / context), URL state. For each, give file:line examples of canonical usage. Flag misuse (e.g., server data in zustand).8. 日志与可观测性
Audit logging conventions: (1) Logger import path, (2) Log shape (JSON vs string), (3) Levels in use (debug / info / warn / error), (4) Where requests are correlated. Output a 5-bullet "log new code like this" guide.9. config / env 处理
Find config conventions: (1) Where env vars are read, (2) Whether wrapped in a typed config module, (3) Per-environment overrides, (4) Secrets vs non-secrets separation, (5) Defaults policy. file:line evidence.10. 并发 / 异步风格
Detect async conventions: (1) async / await vs promise chain, (2) Cancellation strategy (AbortSignal? token?), (3) Background work (queue / event / cron), (4) Timeout patterns. Output dominant + outliers.11. 风格离群清单
Run the conventions you've inferred and find the top 10 files that deviate most. For each: (a) which convention is broken, (b) likely reason (legacy / quick fix / different author), (c) "fix vs leave" recommendation.12. Agent 风格预热
Produce an agent style block under 400 words that I can paste into CLAUDE.md (Claude Code) or AGENTS.md (Codex / Cursor / Copilot / Gemini CLI). Cover: naming, layering, errors, tests, async. Bullets only, no prose intro. Each bullet must be a rule a model can follow on new code, not a description.怎么验证 agent 推断的结果
约定识别会悄无声息地翻车：用三个文件拼出来的、听上去很自信的风格指南，和真正可靠的指南长得一模一样。信它之前先抽查。
- 要证据，然后真去翻。 每条结论都该带
file:line。随机翻两三处，如果引用的那一行根本看不出这个模式，说明 Prompt 过度归纳了。 - 换一批文件再跑一次。 如果两次跑出来的命名”规则”不一样，那是某个作者的习惯，不是约定。
- 和 lint 配置对照。 如果
.eslintrc或biome.json已经写了某条规则，agent 的结论应该一致。不一致通常意味着 lint 配置过时了，这本身就值得知道。 - 找边界。 真实仓库常常带两套风格（老模块 vs 重写）。好的识别会点名这条边界；差的会把两者糊成一团。
容易踩的坑
- 读一个文件就当成全仓风格。
- 把某个作者的偏好当成全仓约定。
- 推行团队从没真正同意过的规矩。
- 让 agent 推风格却不让它读 outlier。
- 写了风格指南却不在
CLAUDE.md/AGENTS.md里链接它，结果没有任何 agent 会读到。 - 禁掉每一个离群——有些是有原因的、故意为之的例外。
- 只看表面风格，漏掉分层、DI、错误模式，而大多数 bug 恰恰出在这里。
优化技巧
- 采样 8-12 个文件，别只 2 个。约定要有广度才显现。
- 凡是机械化的约定，就配一条 lint 规则，让 Prompt 专心处理 lint 表达不了的结构判断。
- 季度跑一次，或者每次大重构之后跑。约定会漂移，而风格文件过时得最快。
- 拿不准时问原作者，别让 agent 自动改。Prompt 能把问题标出来，但答不了意图。
FAQ
- agent 应该采样多少文件？：跨主要目录 8-12 个。少了看不出方差，多了边际收益递减。有 100 万 token 窗口的情况下，可以先让
ripgrep把整个仓库索引一遍，再有选择地读。 - 该让 agent 自动修离群行吗？：不该。离群往往有原因。用
file:line列出来，让人来判断”修还是留”。 - 小仓库能跳过吗？：能。20 文件以内没有值得记录的约定，而且你全读一遍比写 Prompt 还快。
- 这能取代 ESLint / Prettier 吗？：不能，是互补。lint 强制机械规则；约定识别捕捉 lint 表达不了的结构决策（分层、DI、错误策略）。
- 该用 CLAUDE.md 还是 AGENTS.md？：用你的 agent 会读的那个。Claude Code 读
CLAUDE.md；Codex、Cursor、Copilot、Gemini CLI 都读开放的AGENTS.md标准。很多团队两个都留：AGENTS.md当共享源头，再用一个短小的CLAUDE.md指过去。 - 仓库里两套风格冲突怎么办？：都记录下来，点名边界（通常是老代码 vs 重写），并确定迁移方向。别让 agent 把两者平均成一个谁都不像的风格。