Codebase conventions

Codebase Conventions

Extract and document the naming conventions and recurring code patterns of a codebase. The output answers one question: "If I write new code in this project, what conventions do I need to follow so it doesn't look out of place?"

Scope

This skill is narrow by design. It covers ONLY:

• File naming (kebab-case, camelCase, suffixes like .service.ts)
• Function/class naming (factory functions, handlers, hooks)
• Type/interface naming and where types live
• Export patterns (default vs named, barrel files)
• Recurring code patterns (singletons, middleware, decorators, hook composition)

For everything else, point the user to a sister skill: codebase-overview for architecture, codebase-testing-guide for tests, codebase-error-handling for errors, codebase-glossary for domain vocabulary.

What to Produce

A Markdown file with the structure below. Every section must include real, copy-pasteable examples from the actual codebase. No generic descriptions without examples.

# {Project Name} — Code Conventions

> Generated by codebase-conventions on {YYYY-MM-DD}

## File Naming

{Pattern per directory or layer — describe in 2-3 sentences. If different directories use different conventions, say so.}

**Real examples:**
- `{actual/path/to/file-1.ts}`
- `{actual/path/to/file-2.ts}`
- `{actual/path/to/file-3.ts}`

### Common suffixes
{e.g., `.service.ts`, `.repository.ts`, `.routes.ts`, `.utils.ts`, `.test.ts` — what each one signals about the file's role}

## Function & Class Naming

{Patterns — factory functions like `createX`, hooks like `useX`, handlers like `handleX` / `onX`, async functions, etc.}

**Real examples:**
- `{actualFunctionName}` in `{file}` — {what kind of function this is}
- `{actualClassName}` in `{file}` — {what kind of class this is}
- `{actualFunctionName}` in `{file}` — {...}

## Type & Interface Naming

{Where types live (colocated with usage, centralized in `types/`, in a shared package), naming convention (`IFoo` vs `Foo` vs `FooType`), export patterns}

**Real examples:**
- `{TypeName}` in `{file}`
- `{InterfaceName}` in `{file}`

## Export Patterns

{Default exports vs named exports? Barrel files (`index.ts` re-exports)? Re-export conventions?}

**Real example from a representative file:**
\```{language}
{Real export block from an actual file — paste it directly}
\```

## Recurring Code Patterns

For each pattern detected, include a description, where it shows up, and a real snippet.

### {Pattern 1 — e.g., "Service factory pattern"}

{2–3 sentence description of the pattern}

**Where it shows up:** `{file 1}`, `{file 2}`, `{file 3}`

**Snippet:**
\```{language}
{Real code from one of the files above}
\```

### {Pattern 2 — e.g., "React hook composition"}
...

### {Pattern 3 — e.g., "Hono middleware chain"}
...

## Inconsistencies & Notes

{If different parts of the codebase follow different conventions — common when there's a refactor in progress — call them out here. Example: "`packages/core/` uses kebab-case (`user-service.ts`), but `src/` uses camelCase (`userService.ts`) — likely an artifact of the in-progress v0 redesign."}

{If you couldn't determine a clear pattern in some area, list it here with what you observed.}

How to Scan

# File naming patterns — sample broadly
git ls-files --cached --exclude-standard 2>/dev/null | grep -E '\.(ts|tsx|py|go|rs|java)$' | sed 's/.*\///' | sort | head -60

# Common suffixes (e.g., .service.ts, .repository.ts, .routes.ts)
git ls-files 2>/dev/null | sed 's/.*\///' | grep -oP '\.[a-zA-Z]+\.' | sort | uniq -c | sort -rn | head -20

# Function declarations (TS/JS)
grep -rn "^export function\|^export const.*=.*=>\|^function \|^const.*=.*=>" --include="*.ts" --include="*.tsx" 2>/dev/null | head -40

# Class declarations
grep -rn "^export class\|^class " --include="*.ts" --include="*.tsx" --include="*.py" 2>/dev/null | head -30

# Type/interface declarations
grep -rn "^export type\|^export interface" --include="*.ts" --include="*.tsx" 2>/dev/null | head -30

# Export patterns
grep -rn "^export default" --include="*.ts" --include="*.tsx" 2>/dev/null | head -20
grep -rn "^export {" --include="*.ts" --include="*.tsx" 2>/dev/null | head -20

# React hook patterns
grep -rn "^export function use\|^export const use" --include="*.ts" --include="*.tsx" 2>/dev/null | head -20

# Barrel files (index.ts)
find . \( -name "index.ts" -o -name "index.js" \) -not -path '*/node_modules/*' 2>/dev/null | head -20

# Python equivalents
grep -rn "^def \|^class " --include="*.py" 2>/dev/null | head -40

# Go equivalents
grep -rn "^func \|^type " --include="*.go" 2>/dev/null | head -40

When you find an interesting pattern, read the file to copy a real snippet. Don't paraphrase — paste actual code.

Where to Save

Check for an existing docs location:

• If docs/ exists, save as docs/conventions.md
• If documentation/ exists, save as documentation/conventions.md
• If .claude/ exists, save as .claude/conventions.md
• Otherwise propose docs/conventions.md and ask the user before creating

For monorepos, ask the user whether to produce one conventions doc for the whole repo, or one per package — conventions often vary between packages.

Principles

Real examples only. Every section in the output must include at least one real, copy-pasteable example from the actual codebase. Generic descriptions like "files use kebab-case" without showing real file names fail this skill's contract.

Cite locations. When you show an example, include the file path. The user should be able to open the file and see the convention in context.

Quote enough to teach. A 3–5 line code snippet with full context beats a 1-line excerpt. Show the convention in use, not just its name.

Flag inconsistency. If different parts of the codebase follow different conventions, say so explicitly — don't paper over it. This is often the most useful information in the doc, because inconsistency usually signals an in-progress refactor or two-team split.

Don't invent. If you can't find a clear pattern, write "No clear convention detected" and describe what you actually observed. Don't extrapolate from one or two examples.

Don't drift in scope. If you find yourself starting an "Architecture" or "Testing" section, stop. Those belong in sister skills. Note the observation as a one-liner under "See Also" at the end.

After Producing

1. Save the file to the chosen location.
2. In chat, surface the 1–2 most surprising or non-obvious conventions you found — these are the ones a new developer is most likely to violate.
3. If you spotted inconsistencies that suggest an in-progress refactor, call that out — it's signal the team will care about.
4. Provide a path or link to the saved file.