style-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Style Guide: Multi-Agent Convention Analyzer

风格指南：多Agent约定分析器

Spawns specialized analyzer agents to discover and document a codebase's conventions, patterns, and style. Each agent focuses on one aspect and explores independently.

Use this when:

Starting work on an unfamiliar codebase
You want AI to match existing patterns exactly
Making implicit conventions explicit
Before running feature-council on a new project

生成专用分析Agent来发现并记录代码库的编码约定、代码模式和风格规范。每个Agent专注于一个维度并独立进行探索。

适用场景：

开始处理不熟悉的代码库
希望AI完全匹配现有代码模式
将隐式编码约定转化为显式文档
在新项目上运行feature-council之前

Output

输出

Generates

.claude/codebase-style.md

- a comprehensive style guide that can be referenced by other skills and agents.

生成

.claude/codebase-style.md

文件——一份可供其他技能模块和Agent参考的全面风格指南。

CRITICAL: Language-Agnostic Design

核心特性：与语言无关的设计

Each analyzer:

Discovers the language/framework first - Don't assume anything
Finds relevant files itself - Uses Glob, Grep, LS to explore
Extracts patterns from what exists - Not what "should" exist
Reports findings in structured format - For synthesis

This works for: Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, or any other language.

每个分析器遵循以下原则：

先发现语言/框架 - 不做任何假设
自行查找相关文件 - 使用Glob、Grep、LS命令进行探索
从现有代码中提取模式 - 而非基于“应该存在”的规则
以结构化格式报告发现结果 - 便于后续整合

支持的语言包括：Python、JavaScript、TypeScript、Go、Rust、Java、C#、Ruby、PHP、Swift、Kotlin或其他任意语言。

Workflow

工作流程

Step 0: Check for Existing Style Guide

步骤0：检查现有风格指南

Before starting, check if
.claude/codebase-style.md
already exists.

If it exists, ask the user:

A style guide already exists for this codebase (.claude/codebase-style.md).

Options:
1. View the existing style guide
2. Regenerate it (will overwrite)
3. Cancel

What would you like to do?

Only proceed with analysis if the user chooses to regenerate.

开始前，请检查
.claude/codebase-style.md
是否已存在。

如果已存在，向用户询问：

该代码库已存在风格指南文件 (.claude/codebase-style.md)。

选项：
1. 查看现有风格指南
2. 重新生成（将覆盖原文件）
3. 取消

请问您想要执行哪个操作？

仅当用户选择重新生成时，才继续进行分析。

Step 1: Quick Language/Framework Detection

步骤1：快速检测语言/框架

Before spawning analyzers, do a quick check:

bash

undefined

在生成分析Agent之前，先进行快速检测：

bash

undefined

Check for common indicators

检查常见标识文件

ls -la # Look for package.json, requirements.txt, go.mod, Cargo.toml, etc.


Note the primary language(s) and framework(s) detected. Pass this context to analyzers.

ls -la # 查看是否存在package.json、requirements.txt、go.mod、Cargo.toml等文件


记录检测到的主要语言和框架，并将该上下文传递给分析Agent。

Step 2: Spawn Analyzer Agents IN PARALLEL

步骤2：并行生成分析Agent

Spawn ALL analyzers simultaneously with the same context:

CONTEXT: [Primary language/framework detected in Step 1]
TASK: Analyze the codebase for [YOUR SPECIALTY] conventions and patterns.

Return a structured report of what you find.

Task(agent: "style-structure", prompt: "CONTEXT: [lang/framework]. Analyze folder structure, file organization, and module patterns.")
Task(agent: "style-naming", prompt: "CONTEXT: [lang/framework]. Analyze naming conventions for files, variables, functions, classes, constants.")
Task(agent: "style-patterns", prompt: "CONTEXT: [lang/framework]. Analyze code patterns: error handling, data access, configuration, logging.")
Task(agent: "style-testing", prompt: "CONTEXT: [lang/framework]. Analyze testing patterns: file locations, naming, structure, assertions.")
Task(agent: "style-frontend", prompt: "CONTEXT: [lang/framework]. Analyze frontend/UI patterns if applicable: components, styling, state. If not a frontend project, report 'N/A'.")

ALL agents spawn in the SAME batch - parallel execution.

同时生成所有分析Agent，并为其提供相同的上下文：

上下文：[步骤1中检测到的主要语言/框架]
任务：分析代码库中与[您的专业领域]相关的约定和模式。

以结构化格式返回您的发现结果。

Task(agent: "style-structure", prompt: "CONTEXT: [lang/framework]. Analyze folder structure, file organization, and module patterns.")
Task(agent: "style-naming", prompt: "CONTEXT: [lang/framework]. Analyze naming conventions for files, variables, functions, classes, constants.")
Task(agent: "style-patterns", prompt: "CONTEXT: [lang/framework]. Analyze code patterns: error handling, data access, configuration, logging.")
Task(agent: "style-testing", prompt: "CONTEXT: [lang/framework]. Analyze testing patterns: file locations, naming, structure, assertions.")
Task(agent: "style-frontend", prompt: "CONTEXT: [lang/framework]. Analyze frontend/UI patterns if applicable: components, styling, state. If not a frontend project, report 'N/A'.")

所有Agent在同一批次中生成——并行执行。

Step 3: Track Progress

步骤3：跟踪进度

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                   ANALYZER PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☐ Structure Analyzer - Working...
☐ Naming Analyzer - Working...
☐ Patterns Analyzer - Working...
☐ Testing Analyzer - Working...
☐ Frontend Analyzer - Working...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Update as each completes.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                   分析器进度
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☐ 结构分析器 - 运行中...
☐ 命名分析器 - 运行中...
☐ 模式分析器 - 运行中...
☐ 测试分析器 - 运行中...
☐ 前端分析器 - 运行中...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

随着每个分析器完成，更新进度状态。

Step 4: Collect and Synthesize

步骤4：收集并整合结果

Each analyzer returns structured findings. Merge into a unified style guide.

Handle conflicts: If analyzers disagree (rare), note both patterns.

每个分析器返回结构化的发现结果。将这些结果合并为统一的风格指南。

处理冲突： 如果分析器的结果存在分歧（极少发生），请同时记录两种模式。

Step 5: Generate Style Guide

步骤5：生成风格指南

Create

.claude/codebase-style.md

markdown

undefined

创建

.claude/codebase-style.md

文件：

markdown

undefined

Codebase Style Guide

代码库风格指南

Auto-generated by codebase-style skill on [DATE] Primary: [Language] | Framework: [Framework] | [X] files analyzed

由codebase-style技能模块自动生成于 [日期] 主要语言: [语言] | 框架: [框架] | 已分析 [X] 个文件

Project Structure

项目结构

[From style-structure analyzer]

[来自style-structure分析器的结果]

Directory Layout

目录布局

```
src/
```
- Source code
```
tests/
```
- Test files
...

```
src/
```
- 源代码
```
tests/
```
- 测试文件
...

File Organization Pattern

文件组织模式

[Description with examples]

[描述及示例]

Naming Conventions

命名约定

[From style-naming analyzer]

Element	Convention	Example
Files	[pattern]	`user_service.py`
Classes	[pattern]	`UserService`
Functions	[pattern]	`get_user_by_id`
Variables	[pattern]	`user_count`
Constants	[pattern]	`MAX_RETRIES`

[来自style-naming分析器的结果]

元素	约定	示例
文件	[模式]	`user_service.py`
类	[模式]	`UserService`
函数	[模式]	`get_user_by_id`
变量	[模式]	`user_count`
常量	[模式]	`MAX_RETRIES`

Code Patterns

代码模式

[From style-patterns analyzer]

[来自style-patterns分析器的结果]

Error Handling

错误处理

[Actual example from codebase]

[来自代码库的实际示例]

Data Access Pattern

数据访问模式

[Actual example from codebase]

[来自代码库的实际示例]

Logging Pattern

日志模式

[Actual example from codebase]

[来自代码库的实际示例]

Configuration Pattern

配置模式

[Description]

[描述]

Testing Patterns

测试模式

[From style-testing analyzer]

[来自style-testing分析器的结果]

Test Location

测试文件位置

[Where tests live relative to source]

[测试文件相对于源代码的存放位置]

Test Naming

测试命名规范

[Convention for test files and functions]

[测试文件和函数的命名约定]

Test Structure

测试结构

[Actual example from codebase]

[来自代码库的实际示例]

Assertion Style

断言风格

[What assertion library/style is used]

[使用的断言库/风格]

Frontend Patterns (if applicable)

前端模式（如适用）

[From style-frontend analyzer, or "N/A - Not a frontend project"]

[来自style-frontend分析器的结果，或“N/A - 非前端项目”]

Component Structure

组件结构

[Pattern]

[模式]

Styling Approach

样式方案

[CSS-in-JS, Tailwind, CSS Modules, etc.]

[CSS-in-JS、Tailwind、CSS Modules等]

State Management

状态管理

[Pattern]

[模式]

Quick Reference

快速参考

Category	Convention
File naming	[pattern]
Function naming	[pattern]
Error handling	[pattern name]
Test files	[location pattern]
Imports	[order/style]

分类	约定
文件命名	[模式]
函数命名	[模式]
错误处理	[模式名称]
测试文件	[位置模式]
导入	[顺序/风格]

Examples to Follow

参考示例

Good Example (matches codebase style)

符合规范的示例（匹配代码库风格）

[Real example from codebase that exemplifies the patterns]

[来自代码库、能体现模式的真实示例]

Anti-pattern (avoid this)

反模式（应避免）

[What NOT to do based on codebase conventions]

undefined

[基于代码库约定，不应采用的写法]

undefined

Step 6: Save and Report

步骤6：保存并报告结果

Create
```
.claude/
```
directory if needed
Write
```
.claude/codebase-style.md
```
Report summary to user

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 CODEBASE STYLE ANALYSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Analysis Summary

| Analyzer | Files Checked | Patterns Found |
|----------|---------------|----------------|
| Structure | [N] | [N] |
| Naming | [N] | [N] |
| Patterns | [N] | [N] |
| Testing | [N] | [N] |
| Frontend | [N or N/A] | [N or N/A] |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Generated: .claude/codebase-style.md

Key Findings:
- Language: [Primary language]
- Framework: [If detected]
- Naming: [Quick summary, e.g., "snake_case for files, PascalCase for classes"]
- Structure: [Quick summary, e.g., "Feature-based organization"]
- Testing: [Quick summary, e.g., "pytest, tests/ directory"]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 This style guide will be referenced by other skills to ensure
   consistent code that matches your codebase conventions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

若需要，创建
```
.claude/
```
目录
写入
```
.claude/codebase-style.md
```
文件
向用户报告分析摘要

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                 代码库风格分析完成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 分析摘要

| 分析器 | 检查文件数 | 发现模式数 |
|----------|---------------|----------------|
| 结构 | [N] | [N] |
| 命名 | [N] | [N] |
| 模式 | [N] | [N] |
| 测试 | [N] | [N] |
| 前端 | [N 或 N/A] | [N 或 N/A] |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 已生成文件: .claude/codebase-style.md

关键发现:
- 语言: [主要语言]
- 框架: [如已检测到]
- 命名规范: [快速摘要，例如："文件使用snake_case，类使用PascalCase"]
- 项目结构: [快速摘要，例如："基于功能的组织方式"]
- 测试方案: [快速摘要，例如："使用pytest，测试文件存放在tests/目录"]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 此风格指南可供其他技能模块参考，以确保代码符合代码库约定，保持一致性。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Agents

Agent说明

5 specialized analyzer agents in

agents/

directory:

Agent	Focus	What It Looks For
`style-structure`	Organization	Folders, modules, file grouping, imports
`style-naming`	Naming	Files, variables, functions, classes, constants
`style-patterns`	Code patterns	Error handling, data access, logging, config
`style-testing`	Testing	Location, naming, structure, assertions
`style-frontend`	Frontend/UI	Components, styling, state (if applicable)

All analyzers:

Explore the codebase independently
Language-agnostic (detect, don't assume)
Return structured findings
Use Read, Grep, Glob, LS tools

agents/

目录下包含5个专用分析Agent：

Agent	专注领域	分析内容
`style-structure`	组织架构	文件夹、模块、文件分组、导入方式
`style-naming`	命名规范	文件、变量、函数、类、常量的命名
`style-patterns`	代码模式	错误处理、数据访问、日志、配置
`style-testing`	测试方案	测试文件位置、命名、结构、断言方式
`style-frontend`	前端/UI	组件、样式、状态管理（如适用）

所有分析器具备以下特性：

独立探索代码库
与语言无关（自动检测，不做假设）
返回结构化发现结果
使用Read、Grep、Glob、LS工具

Integration with Other Skills

与其他技能模块的集成

The generated

.claude/codebase-style.md

can be referenced by:

feature-council - Agents can check style guide before implementing
debug-council - Ensure fixes match codebase patterns
parallel-builder - Each builder follows the style guide

To explicitly include:

Before implementing, read .claude/codebase-style.md to understand codebase conventions.

生成的

.claude/codebase-style.md

文件可供以下模块参考：

feature-council - Agent在实现功能前可查阅风格指南
debug-council - 确保修复方案符合代码库模式
parallel-builder - 每个构建器遵循风格指南

如需显式引用，可添加：

在实现前，请阅读.claude/codebase-style.md以了解代码库约定。

When to Re-run

重新运行时机

Run

codebase-style

again when:

Major refactoring has occurred
New patterns have been introduced
Moving to a new framework/library
Style guide feels outdated

在以下场景下重新运行

codebase-style

：

进行了重大重构
引入了新的代码模式
迁移到新的框架/库
风格指南已过时

Triggers

触发词

"style guide"
"generate style guide"
"analyze codebase style"
"what are the conventions in this codebase"
"codebase conventions"
"analyze this codebase"
"extract code style"
"document coding patterns"

"style guide"
"generate style guide"
"analyze codebase style"
"what are the conventions in this codebase"
"codebase conventions"
"analyze this codebase"
"extract code style"
"document coding patterns"