“跟着代码风格写”是诚实建议，但你说不清那风格是什么，就写不出一致的代码。好的约定识别 Prompt 要把”隐式”变”显式”：哪些模式反复出现、哪些是例外、哪些只是 cargo-cult。
适合哪些场景
接手陌生代码库的工程师、外包进入客户仓的承包者、希望 AI agent 守家规的工具构建者。
什么时候不建议这样写 Prompt
少于 20 文件的项目别用——约定要规模才显现。也别用来强推团队不想要的规矩。
Prompt 结构公式
每个约定识别 Prompt 都要带这六个要素：
- 角色：AI 扮演谁（SRE / Release Captain / staff 工程师 / QA Lead）。
- 上下文：技术栈 / 分支 / 失败日志 / diff / dashboard URL。
- 目标：一个具体可交付物——根因、checklist、计划、ticket 列表、runbook。
- 限制：AI 不能做什么（别自动修、别瞎造文件路径）。
- 输出格式：编号清单、markdown 表格、JSON、unified diff、可运行代码。
- 示例 / 信号：1-2 条”好输出”示例，或反例。
这套 Prompt 适合用在哪
- 入职陌生代码库
- 产出 house-style 文档
- 给 AI agent 预热，让它写的代码贴合风格
- 检测模块之间的漂移
- 迁移目标的风格指南
12 个可直接复制的 Prompt 模板
1. house-style 检测扫描
Read 10 representative files from this repo. 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.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 a CLAUDE.md "house style" section ≤ 400 words that I can paste into the repo so any AI agent will match style on new code. Cover: naming, layering, errors, tests, async. No prose intro — bullets only.容易踩的坑
- 读一个文件就当全仓风格。
- 把某作者偏好当成全队约定。
- 推行全队并不真心同意的规矩。
- 让 AI 推风格但不让它读 outlier。
- 写了风格指南却不在 CLAUDE.md 里链接。
- 禁掉每一个离群——有些是有意为之。
- 只看代码风格，不看分层 / DI / 错误模式。
优化技巧
- 抽样 8-12 个文件，不要 2 个。
- 看 outlier——能看出团队主动排斥什么。
- 把推断出的指南放进
CLAUDE.md，agent 跟着写。 - 季度跑一次，约定会漂移。
- 机械化部分用 lint 配合 prompt。
- 拿不准时问原作者，别让 AI 自动改。
- 命名和分层收益最大，注释和 import 顺序次之。
实操加深
使用这些 prompt 时，不要只替换一个主题词就直接交付。围绕「代码约定识别 Prompt：12 个读懂陌生仓库的模板」先补齐受众、渠道、长度、语气、参考样例、禁止样式和成功标准，再让模型输出 2 个不同版本做横向比较。好的结果应该能被另一个人直接复用，而不是只有顺滑但空泛的表达。
如果输出看起来像通用模板，下一轮要增加一个真实场景、一个反例和一个可检查指标，例如点击率、转化动作、字数、平台限制或品牌禁区。这样改出来的内容才更像可用资产，而不是一次性的灵感草稿。
FAQ
- 采样多少文件？: 8-12 个，覆盖各主要目录。少了看不出方差。
- 让 AI 自动修离群行吗？: 别——离群往往有原因。让 AI 列出来，人来 triage。
- 小仓库可以跳过吗？: 20 文件以内不需要专门文档。
- 这能取代 ESLint / Prettier 吗？: 互补——lint 管机械，约定识别管结构。
- 怎么保持文档不过时？: 季度或大重构后重跑，更新 CLAUDE.md。
- 仓库里两套风格冲突怎么办？: 都记录、指出边界、确定迁移方向。