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.

执行对当前代码库的深度分析，生成（或重新生成）STYLE_GUIDE.md文件，为每一条规范提供完整的证据引用。

与/setup-ai的区别及适用场景：
/setup-ai
是在项目初始化阶段生成简易版风格指南。本技能适用于你需要完整版本的场景——包含17个章节，每一条规范都有具体的文件引用作为支撑，同时会标记不一致之处供人工决策。你可以在运行/setup-ai之后执行本技能以获得更深入的结果，或者在代码约定出现偏差时单独运行。

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.

仅记录你在代码中实际观察到的模式。绝对不要臆造或假设约定。
如果代码库中的模式不一致，标记出不一致之处，并询问用户要标准化为哪一种约定。

引用具体文件作为证据："基于

src/services/UserService.ts

、

src/services/OrderService.ts

..."

如果已经存在STYLE_GUIDE.md，先读取该文件，在其基础上优化/整合内容，而不是直接覆盖。

Analysis Process

分析流程

Step 1: Detect Tech Stack

步骤1：检测技术栈

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.

搜索依赖和配置文件：

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

读取依赖文件以识别：语言版本、框架及版本、核心库、构建工具、测试框架、linter/formatter配置。

Step 2: Read Existing Configuration

步骤2：读取现有配置

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.

检查已有的定义了规则的风格/约定文档：

```
.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
```

这些是权威来源——直接从中提取规则。

Step 3: Sample Code for Patterns

步骤3：采样代码提取模式

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

读取10-15个代表性文件——有策略地采样，不要尝试读取所有文件：

3-4个"核心"文件（模型、服务、控制器、组件）
2-3个测试文件
1-2个配置/初始化文件
1-2个工具/辅助函数文件
1个入口文件或路由文件

针对每个文件，提取以下方面的模式：

命名：变量、函数、类、文件使用camelCase、snake_case、PascalCase还是kebab-case
文件命名：
```
*.service.ts
```
、
```
*_controller.rb
```
、
```
*.spec.js
```
等
导入：排序（标准库→外部→内部）、风格（命名导入vs默认导入）、路径别名
导出：命名导出、默认导出、module.exports、桶文件
错误处理：try/catch、Result类型、错误中间件、rescue块
注释：风格、密度、JSDoc/RDoc/docstrings
类型：TypeScript严格模式、JSDoc注解、Python类型提示、无类型
函数：箭头函数 vs 函数声明、参数模式、返回风格、async/await

Step 4: Identify Testing Patterns

步骤4：识别测试模式

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

从测试文件中提取：

框架（Jest、Vitest、RSpec、pytest、Go testing等）
文件命名约定（
```
*_test.rb
```
、
```
*.spec.ts
```
、
```
*.test.js
```
、
```
test_*.py
```
）
测试结构（describe/it、test()、基于类、表驱动）
Fixture/factory模式
Mocking方案（jest.mock、factory_bot、unittest.mock）
断言风格（expect().toBe、assert、should）
测试文件是就近存放还是放在独立目录

Step 5: Check Git History (if available)

步骤5：检查Git历史（如果可用）

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.)

运行

git log --oneline -20

查看：

提交信息格式（约定式提交？工单引用？自由格式？）

运行

git branch -a | head -20

查看：

分支命名约定（feature/、fix/等）

Generate: STYLE_GUIDE.md

生成：STYLE_GUIDE.md

Write to the project root. Use this structure:

markdown

undefined

写入到项目根目录。使用以下结构：

markdown

undefined

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.]

[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.]

undefined

[Patterns found in the codebase that should NOT be followed in new code. Legacy approaches being phased out. Inconsistencies being resolved.]

undefined

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."

向用户展示摘要：你发现了什么、哪些部分是明确的、哪些内容存在歧义
高亮所有需要人工决策的不一致之处
告知用户："请审阅此文件。我从你的代码中提取了这些模式，但你的团队才了解背后的意图。请修改所有错误的内容，或者将期望的约定而非现有实际约定补充进去。"
如果还不存在AGENTS.md，建议："运行
```
/setup-ai
```
生成你的AGENTS.md和CLAUDE.md，之后它会自动引用STYLE_GUIDE.md。"
建议："在PR提交前运行
```
/review-style-guide
```
，可以自动根据本风格指南检查新代码。"

generate-comprehensive-style-guide

Original

Translation

Generate Comprehensive Style Guide

生成全面风格指南

Rules

规则

Analysis Process

分析流程

Step 1: Detect Tech Stack

步骤1：检测技术栈

Step 2: Read Existing Configuration

步骤2：读取现有配置

Step 3: Sample Code for Patterns

步骤3：采样代码提取模式

Step 4: Identify Testing Patterns

步骤4：识别测试模式

Step 5: Check Git History (if available)

步骤5：检查Git历史（如果可用）

Generate: STYLE_GUIDE.md

生成：STYLE_GUIDE.md

Coding Style Guide

Coding Style Guide

Language & Formatting

Language & Formatting

Naming Conventions

Naming Conventions

Files & Directories

Files & Directories

Variables & Functions

Variables & Functions

Classes, Types & Interfaces

Classes, Types & Interfaces

Constants

Constants

Database

Database

Code Organization

Code Organization

File Structure

File Structure

Import Ordering

Import Ordering

Function Patterns

Function Patterns

Error Handling

Error Handling

Testing Standards

Testing Standards

File Naming

File Naming

Test Structure

Test Structure

What to Test

What to Test

Fixtures & Mocking

Fixtures & Mocking

API Patterns

API Patterns

Database Patterns

Database Patterns

Component Patterns (if frontend)

Component Patterns (if frontend)

Git Conventions

Git Conventions

Anti-Patterns — Do NOT Replicate

Anti-Patterns — Do NOT Replicate

After Generation

生成后操作