“Just match the codebase style” is honest advice — but if you can’t articulate what that style IS, you can’t match it. A good convention-detection prompt makes the implicit explicit: which patterns repeat, which are exceptions, and which look like cargo-cult.
Who this is for
Engineers onboarding to an inherited codebase, contractors stepping into a new client repo, AI tooling builders who want their agents to follow house style.
When not to use these prompts
Don’t use these on a < 20-file project — convention emerges with scale. Don’t use them to enforce conventions you don’t actually want.
Prompt anatomy / structure formula
Every convention-detection prompt should carry six elements:
- Role: who AI plays (SRE / release captain / staff engineer / QA lead).
- Context: stack / branch / failing logs / diff / dashboard URL.
- Goal: one concrete deliverable — root cause, checklist, plan, ticket list, runbook.
- Constraints: what AI MUST NOT do (don’t auto-fix, don’t hallucinate file paths).
- Output format: numbered findings, markdown table, JSON, unified diff, runnable code.
- Examples / signal: 1-2 “good” output examples, or counter-examples.
Best for
- Onboarding to an unfamiliar codebase
- Producing a house-style doc
- Pre-flighting an AI agent so its code matches existing style
- Detecting drift between modules
- Migration target style guide
12 copy-ready prompt templates
1. House-style detection scan
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. 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 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.Common mistakes
- Reading 1 file and assuming it’s the whole style.
- Mistaking a single author’s preference for repo convention.
- Enforcing conventions the team doesn’t actually agree on.
- Letting AI infer convention without sampling outliers.
- Writing the style guide and never linking it from CLAUDE.md.
- Banning every outlier — some are intentional exceptions.
- Detecting only style; missing layering / DI / error patterns.
How to push results further
- Sample 8-12 files, not 2. Convention emerges with breadth.
- Always look at outliers — they tell you what the team actively rejects (or hasn’t cleaned up).
- Drop the inferred style guide into
CLAUDE.mdso agents stay in style. - Run the detection quarterly — conventions drift.
- Pair convention detection with a lint rule when the convention is mechanical.
- When in doubt, ask the original author rather than auto-enforce.
- Naming and layering pay off most. Comments and import order are minor.
Practical depth notes
Use these prompts as starting points, not final answers. For Codebase Convention Detection Prompts: 12 Templates to Read a New Repo, the useful extra work is to replace every generic placeholder with a real constraint: audience, channel, length, brand voice, examples to imitate, and examples to avoid. Run at least two versions with different constraints, then compare the outputs side by side instead of accepting the first polished response.
A good result should pass three checks: it is specific enough that another person could reuse it, it avoids vague praise or filler, and it gives you an editable artifact rather than a broad suggestion. If the output feels generic, add one concrete reference, one forbidden pattern, and one measurable success criterion before rerunning the prompt. One final check: compare the finished result against the original goal in a single sentence. If that sentence is hard to write, the output is probably polished but unfocused. Tighten the goal, remove decorative language, and rerun only the weak section instead of regenerating the entire piece.
FAQ
- How many files to sample?: 8-12 across the major directories. Less misses variance; more is diminishing returns.
- Should AI auto-fix outliers?: No — outliers often have a reason. Surface them, let humans triage.
- Can I skip this on small repos?: Yes — under 20 files, conventions don’t need a doc.
- Does this replace ESLint / Prettier?: Complements them. Lint covers mechanical; convention detection covers structural.
- How do I keep the doc fresh?: Re-run quarterly or after a major refactor; update CLAUDE.md.
- What if the repo has two conflicting styles?: Document both, name the boundary, decide direction of migration.