“Just match the codebase style” is honest advice, but if you can’t articulate what that style IS, you can’t match it. A convention-detection prompt makes the implicit explicit: which patterns repeat, which are exceptions, and which are cargo-cult left over from a copy-paste three years ago. With a 1M-token context window now standard on Claude Opus 4.7 and Sonnet 4.6 (roughly 50,000-75,000 lines of code in one window, as of June 2026), an agent can finally sample enough of a repo to tell a real convention from one person’s habit.
TL;DR
- Sample 8-12 files across the major directories, not 1-2. Convention only emerges with breadth.
- Always ask the prompt to surface outliers with
file:lineevidence. Outliers tell you what the team rejects, or hasn’t cleaned up yet. - Detect five things in priority order: naming, layering, error handling, tests, async. Naming and layering pay off most; comment style and import order are noise.
- Pipe the result into the agent config file your team actually uses (
CLAUDE.md,AGENTS.md, or.cursor/rules/) so new AI-written code matches on the first try. - This complements ESLint/Prettier; it does not replace them. Lint covers mechanical rules, convention detection covers structural decisions.
Who this is for
Engineers onboarding to an inherited codebase, contractors stepping into a new client repo, and tooling builders who want their agents to follow house style instead of inventing a fresh one each session.
When not to use these prompts
Skip them on a repo under ~20 files. Convention needs scale to be real, and at that size you can just read everything. And don’t use detection to enforce a “convention” the team never agreed on. The prompt tells you what the code does, not what it should do.
Why context window size changed this
Older agents could only read a handful of files before the window filled, so they over-generalized from a tiny sample. As of June 2026 that constraint is mostly gone:
- Claude Opus 4.7 / Sonnet 4.6 ship a 1M-token context as standard (no beta flag, no surcharge). That is roughly 830K usable tokens, or thousands of source files.
- Gemini 3.1 Pro also offers 1M tokens.
- ChatGPT (GPT-5.5) exposes ~320 pages of in-app context on Plus; the full 1M window is reserved for the $200 Pro tier.
Bigger windows do not mean “paste the whole monorepo.” The cheaper move is to let the agent run ripgrep (rg) to find every type, function, and export with line numbers first, then read only the surrounding context. That keeps the sample representative while spending a few thousand tokens up front to save tens of thousands later. Tell the prompt to work this way.
Where the output should go
A detected convention is only useful if an agent reads it next session. As of June 2026 the three dominant homes are:
| Target file | Tool that reads it | Notes |
|---|---|---|
CLAUDE.md | Claude Code (Anthropic models only) | Layered: ~/.claude/CLAUDE.md global, repo-root project, per-folder, plus gitignored CLAUDE.local.md |
AGENTS.md | Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed | Open standard (Linux Foundation, 60K+ repos); plain markdown, no required structure |
.cursor/rules/*.mdc | Cursor | Per-rule .mdc files, glob-scoped so React rules load only in component files |
Keep the house-style section tight. Models reliably follow roughly 150-200 distinct instructions per context window, and Claude Code’s own system prompt already uses about 50 of those slots. A 400-word, bullet-only style block beats a 2,000-word essay no agent finishes reading.
12 copy-ready prompt templates
Each prompt assumes the agent can read the repo (Claude Code, Cursor, Codex CLI, or an IDE assistant with file access). Where a prompt says “across the repo,” let the tool use rg rather than dumping files into the prompt by hand.
1. House-style detection scan
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. Naming patterns
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. Error-handling style
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. Layering / module boundaries
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. Test conventions
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. Dependency injection style
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. State-management convention
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. Logging + observability
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 handling
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. Concurrency / async style
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. Style outlier hotlist
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 style preload
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.How to verify what the agent inferred
Convention detection fails quietly: a confident-sounding style guide built from three files looks identical to a good one. Spot-check it before you trust it.
- Ask for evidence, then open it. Every claim should carry a
file:line. Open two or three at random. If the cited line doesn’t show the pattern, the prompt over-generalized. - Re-run on a different file sample. If naming “rules” change between runs, you have one author’s habit, not a convention.
- Cross-check against lint config. If
.eslintrcorbiome.jsonalready encodes a rule, the agent’s claim should agree. Disagreement usually means the lint config is stale, which is worth knowing. - Look for the boundary. Real repos often carry two styles (old module vs rewrite). A good detection names the boundary; a weak one averages them into mush.
Common mistakes
- Reading 1 file and treating it as the whole style.
- Mistaking a single author’s preference for a repo-wide convention.
- Enforcing conventions the team never actually agreed on.
- Letting the agent infer convention without sampling outliers.
- Writing the style guide and never linking it from
CLAUDE.md/AGENTS.md, so no agent ever reads it. - Banning every outlier; some are intentional exceptions with a reason.
- Detecting only surface style while missing layering, DI, and error patterns, which is where most bugs come from.
How to push results further
- Sample 8-12 files, not 2. Convention emerges with breadth.
- Pair convention detection with a lint rule whenever the convention is mechanical. Let the prompt handle the structural calls lint can’t express.
- Re-run quarterly, or after any major refactor. Conventions drift, and the style file goes stale fastest.
- When in doubt, ask the original author rather than auto-enforcing. The prompt can flag the question; it can’t answer intent.
FAQ
- How many files should the agent sample?: 8-12 across the major directories. Fewer misses variance; more hits diminishing returns. With a 1M-token window you can afford to let
ripgrepindex the whole repo first, then read selectively. - Should the agent auto-fix outliers?: No. Outliers often have a reason. Surface them with
file:lineand let a human triage “fix vs leave.” - Can I skip this on small repos?: Yes. Under ~20 files there’s no convention worth documenting, and you can read the whole thing faster than you can prompt for it.
- Does this replace ESLint / Prettier?: No, it complements them. Lint enforces mechanical rules; convention detection captures the structural decisions (layering, DI, error strategy) that lint can’t express.
- CLAUDE.md or AGENTS.md?: Use whatever your agent reads. Claude Code reads
CLAUDE.md; Codex, Cursor, Copilot, and Gemini CLI all read the openAGENTS.mdstandard. Many teams keep both, withAGENTS.mdas the shared source and a shortCLAUDE.mdthat points to it. - What if the repo has two conflicting styles?: Document both, name the boundary (usually old code vs a rewrite), and decide the direction of migration. Don’t let the agent average them into a style that matches neither.