Generate Comprehensive Style Guide

Perform a deep analysis of this codebase and generate (or regenerate) a STYLE_GUIDE.md file with full evidence citations for every convention.

When to use this vs
/setup-ai
:
/setup-ai
generates a quick-pass style guide as part of initial project setup. This skill is for when you need the thorough version — 17 sections, every convention backed by specific file citations, inconsistencies flagged for human decision. Run this after
/setup-ai
for more depth, or independently when conventions have drifted.

Rules

ONLY document patterns you actually observe in the code. Never hallucinate or assume conventions.
When patterns are inconsistent across the codebase, note the inconsistency and ask the user which convention to standardize on.

Cite specific files as evidence: "Based on

src/services/UserService.ts

src/services/OrderService.ts

..."

If a STYLE_GUIDE.md already exists, read it first and improve/incorporate rather than overwriting.

Analysis Process

Step 1: Detect Tech Stack

Search for dependency and config files:

File	Stack
`package.json`	Node.js / JavaScript / TypeScript
`tsconfig.json`	TypeScript specifically
`Gemfile`	Ruby
`requirements.txt` , `pyproject.toml` , `Pipfile`	Python
`go.mod`	Go
`Cargo.toml`	Rust
`composer.json`	PHP
`pom.xml` , `build.gradle`	Java / Kotlin
`.csproj` , `.sln`	C# / .NET

Read the dependency file to identify: language version, framework and version, key libraries, build tools, testing framework, linter/formatter configuration.

Step 2: Read Existing Configuration

Check for existing style/convention docs that define rules:

```
.eslintrc
```
,
```
.eslintrc.json
```
,
```
.eslintrc.js
```
```
.prettierrc
```
,
```
.prettierrc.json
```
```
.rubocop.yml
```
```
.editorconfig
```
```
biome.json
```
,
```
biome.jsonc
```
```
ruff.toml
```
,
```
pyproject.toml
```
(ruff/black sections)
```
CLAUDE.md
```
,
```
AGENTS.md
```
,
```
.cursorrules
```

These are authoritative — extract rules from them directly.

Step 3: Sample Code for Patterns

Read 10-15 representative files — sample strategically, don't try to read everything:

3-4 "core" files (models, services, controllers, components)
2-3 test files
1-2 configuration/setup files
1-2 utility/helper files
1 entry point or router file

For each file, extract patterns for:

Naming: camelCase, snake_case, PascalCase, kebab-case — for variables, functions, classes, files
File naming:
```
*.service.ts
```
,
```
*_controller.rb
```
,
```
*.spec.js
```
, etc.
Imports: ordering (stdlib → external → internal), style (named vs default), path aliases
Exports: named exports, default exports, module.exports, barrel files
Error handling: try/catch, Result types, error middleware, rescue blocks
Comments: style, density, JSDoc/RDoc/docstrings
Types: TypeScript strict mode, JSDoc annotations, Python type hints, none
Functions: arrow vs declaration, parameter patterns, return style, async/await

Step 4: Identify Testing Patterns

From the test files:

Framework (Jest, Vitest, RSpec, pytest, Go testing, etc.)
File naming convention (
```
*_test.rb
```
,
```
*.spec.ts
```
,
```
*.test.js
```
,
```
test_*.py
```
)
Test structure (describe/it, test(), class-based, table-driven)
Fixture/factory patterns
Mocking approach (jest.mock, factory_bot, unittest.mock)
Assertion style (expect().toBe, assert, should)
Test file co-location vs separate directory

Step 5: Check Git History (if available)

Run

git log --oneline -20

to see:

Commit message format (conventional commits? Ticket refs? Free-form?)

Run

git branch -a | head -20

to see:

Branch naming convention (feature/, fix/, etc.)

Generate: STYLE_GUIDE.md

Write to the project root. Use this structure:

markdown

# Coding Style Guide

> Auto-generated from codebase analysis on [date]. Review and adjust — these patterns were extracted from your existing code. Where patterns were inconsistent, the most common convention was chosen.

## Language & Formatting
[Indentation: tabs or spaces, width. Line length limit. Semicolons. Quote style. Trailing commas.]
**Evidence:** Based on [cite 2-3 representative files]

## Naming Conventions

### Files & Directories
[Pattern with real examples from the codebase]

### Variables & Functions
[camelCase / snake_case / etc. with real examples]

### Classes, Types & Interfaces
[PascalCase / etc. with real examples]

### Constants
[UPPER_SNAKE_CASE / etc.]

### Database
[Column naming (snake_case?), table naming (plural?), migration naming]

## Code Organization

### File Structure
[Standard order within a file: imports → types → constants → main logic → helpers → exports]
**Evidence:** [cite a file that exemplifies this pattern]

### Import Ordering
[Standard order: stdlib/framework → external packages → internal modules → relative imports]
[Are there path aliases? (@/ or ~/)]

## Function Patterns
[Arrow functions vs declarations. When to use each. Parameter destructuring. Return style. Async/await conventions.]
**Evidence:** [cite examples]

## Error Handling
[The standard error handling pattern — with a real code example copied from the codebase]

## Testing Standards

### File Naming
[Pattern: `*.spec.ts`, `*_test.rb`, etc.]

### Test Structure
[describe/it blocks, test() calls, class-based — with skeleton example]

### What to Test
[Unit tests for what, integration tests for what, what coverage is expected]

### Fixtures & Mocking
[How test data is set up. How external dependencies are mocked.]

## API Patterns
[Endpoint naming. Request validation. Response format (envelope? direct?). Error response format. Status code conventions.]

## Database Patterns
[Migration style. Model/schema definitions. Query conventions. Transactions.]

## Component Patterns (if frontend)
[Component file structure. Props patterns. State management. Styling approach.]

## Git Conventions
[Commit message format. Branch naming. PR description expectations.]

## Anti-Patterns — Do NOT Replicate
[Patterns found in the codebase that should NOT be followed in new code. Legacy approaches being phased out. Inconsistencies being resolved.]

After Generation

Present a summary to the user: what you found, what looks solid, what was ambiguous
Highlight any inconsistencies that need a human decision
Tell the user: "Review this file. I extracted these patterns from your code but your team knows the intent. Edit anything that's wrong or aspirational rather than actual."
If AGENTS.md doesn't exist yet, suggest: "Run
```
/setup-ai
```
to generate your AGENTS.md and CLAUDE.md, then it will reference STYLE_GUIDE.md automatically."
Suggest: "Run
```
/review-style-guide
```
before PRs to automatically check new code against this style guide."

generate-comprehensive-style-guide

NPX Install

Tags

SKILL.md Content