SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场generate-comprehensive-style-guide

generate-comprehensive-style-guide

编程与开发

查看项目

更新于 10-16 04:18

技能介绍

用途

本技能对一个代码库执行深度分析，生成（或重新生成）一份 STYLE_GUIDE.md 文件，其中每一条约定都附带完整的证据引用。

它适用于以下情况：/setup-ai 在项目初始化时生成的只是快速版风格指南，当你需要更详尽的版本——17 个章节、每条约定都有具体文件引用、不一致之处被标注出来交由人工决策时，使用本技能。可在 /setup-ai 之后运行以获得更深度的结果，或在代码约定已经漂移时独立运行。

核心规则

  • 只记录在代码中实际观察到的模式，绝不臆造或假设约定。
  • 当代码库中模式不一致时，记录该不一致，并询问用户希望以哪条约定作为标准。
  • 引用具体文件作为证据，例如：“基于 src/services/UserService.ts、src/services/OrderService.ts……”。
  • 如果已存在 STYLE_GUIDE.md，先阅读它，进行改进与整合，而不是直接覆盖。

分析流程

第 1 步：检测技术栈

搜索依赖与配置文件，据以识别语言、框架与版本、关键库、构建工具、测试框架、代码检查/格式化配置：

  • package.json——Node.js / JavaScript / TypeScript
  • tsconfig.json——TypeScript
  • 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

第 2 步：读取现有配置

检查定义规则的现有风格/约定文档，这些属于权威来源，应直接从中提取规则：

  • .eslintrc、.eslintrc.json、.eslintrc.js
  • .prettierrc、.prettierrc.json
  • .rubocop.yml
  • .editorconfig
  • biome.json、biome.jsonc
  • ruff.toml、pyproject.toml（ruff/black 段落）
  • CLAUDE.md、AGENTS.md、.cursorrules

第 3 步：抽样代码以提取模式

阅读 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、桶文件（barrel files）
  • 错误处理：try/catch、Result 类型、错误中间件、rescue 块
  • 注释：风格、密度、JSDoc/RDoc/文档字符串
  • 类型：TypeScript 严格模式、JSDoc 注解、Python 类型提示、无类型
  • 函数：箭头函数 vs 声明式、参数模式、返回风格、async/await

第 4 步：识别测试模式

从测试文件中分析：

  • 框架（Jest、Vitest、RSpec、pytest、Go testing 等）
  • 文件命名约定（_test.rb、.spec.ts、.test.js、test_.py）
  • 测试结构（describe/it、test()、基于类、表驱动）
  • 夹具/工厂模式
  • 模拟方式（jest.mock、factory_bot、unittest.mock）
  • 断言风格（expect().toBe、assert、should）
  • 测试文件与源码同目录还是分离目录

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

  • 运行 git log --oneline -20 查看提交信息格式（规范提交？工单引用？自由格式？）
  • 运行 git branch -a | head -20 查看分支命名约定（feature/、fix/ 等）

生成 STYLE_GUIDE.md

写入项目根目录，使用如下结构：

  • 标题：Coding Style Guide，并附自动生成说明（日期、来自代码库分析、请审阅调整，不一致处已选用最常见的约定）
  • Language & Formatting（缩进、行宽、分号、引号、尾逗号，附带证据文件）
  • Naming Conventions（文件与目录、变量与函数、类/类型/接口、常量、数据库命名）
  • Code Organization（文件内结构顺序、导入顺序与路径别名）
  • Function Patterns（箭头函数 vs 声明式、参数解构、返回风格、async/await）
  • Error Handling（标准错误处理模式与真实代码示例）
  • Testing Standards（文件命名、测试结构、测试范围、夹具与模拟）
  • API Patterns（端点命名、请求校验、响应格式、错误响应格式、状态码约定）
  • Database Patterns（迁移风格、模型/模式定义、查询约定、事务）
  • Component Patterns（如为前端：组件文件结构、Props 模式、状态管理、样式方案）
  • Git Conventions（提交信息格式、分支命名、PR 描述要求）
  • Anti-Patterns — Do NOT Replicate（不应在新代码中复制的模式、正在淘汰的遗留做法、正在解决的不一致）

生成之后

  • 向用户呈现摘要：发现了什么、哪些看起来稳固、哪些存在歧义。
  • 突出需要人工决策的不一致之处。
  • 告知用户：“审阅此文件。我从你的代码中提取了这些模式，但你的团队了解真实意图。请修改任何错误或属于期望而非现状的内容。”
  • 如果 AGENTS.md 尚不存在，建议：“运行 /setup-ai 生成 AGENTS.md 和 CLAUDE.md，之后它会自动引用 STYLE_GUIDE.md。”
  • 建议：“在提交 PR 前运行 /review-style-guide，自动依据本风格指南检查新代码。”

限制

具体支持的语言列表、检测精度的边界、与其他技能的依赖关系等细节，资料中暂未提供。该技能只依据代码中可观察到的模式生成文档，无法判断团队的真实意图或约定是否恰当。