1. 项目概述当AI成为你的“野生”搭档最近和几个团队的技术负责人聊天大家不约而同地提到了同一个痛点现在用AI辅助写代码的效率确实上来了但代码质量却有点“开盲盒”的感觉。你让AI生成一个函数它可能逻辑上没问题但命名风格一会儿是camelCase一会儿是snake_case导入的模块顺序混乱甚至在一些关键的地方缺少必要的类型注解或错误处理。这感觉就像请了一个能力超强但做事不拘小节的“野生”程序员搭档活儿干得快但留下的“战场”需要你花大量时间去打扫和规范。这正是“AI写的代码总是不规范这个Skill拯救你”这个标题背后我们正在共同面对的真实场景。这里的“Skill”并非指某个单一的、特定的工具比如某个叫“Codex规范开发代码的Skill”的未知产品而是一种将代码规范检查与修复能力深度集成到AI编程工作流中的解决方案或实践模式。它可能是一个IDE插件、一个CLI工具、一个Git钩子脚本或者是一个能理解你团队编码规范的AI Agent。其核心目标非常明确让AI在生成代码的那一刻就自动符合既定的编码规范将“事后lint”转变为“实时纠正”。无论你是使用TypeScript构建前端应用还是用Python进行数据分析、爬虫乃至量化交易这个问题都普遍存在。AI模型无论是GitHub Copilot、ChatGPT还是Claude Code基于海量公开代码训练其学到的“规范”是混杂的。直接使用其原始输出轻则导致代码库风格不一降低可读性重则可能引入潜在的风格冲突在团队协作和代码审查中造成额外负担。因此这个“Skill”的价值就在于充当AI与你的项目规范之间的“翻译官”或“质检员”确保产出的代码不仅能用而且整洁、一致、易于维护。2. 核心思路从“事后纠错”到“实时规训”要解决AI代码不规范的问题最朴素的想法是等AI写完我再手动跑一遍ESLint、Prettier、Black、isort之类的工具去格式化不就行了这个方法当然可行但属于典型的“亡羊补牢”。它打断了流畅的编程心流你需要从思考逻辑的上下文切换出来去执行一个修复命令有时甚至需要来回调整提示词Prompt来让AI“理解”你的要求。我们的目标是追求一种更优雅、更自动化的方式让规范检查发生在代码诞生的瞬间或者至少是融入生成过程之中。2.1 设计理念拆解这个“Skill”的设计核心是建立一个规范前置的AI交互管道。其工作流可以抽象为以下几个关键环节规范定义与加载首先你需要有一份机器可读的编码规范。对于TypeScript/JavaScript这通常是.eslintrc.js、.prettierrc对于Python则是pyproject.toml、.flake8、setup.cfg等。这个“Skill”需要能读取并理解这些配置。AI代码生成用户通过自然语言或代码片段向AI模型可能是本地运行的也可能是调用云端API请求生成代码。实时分析与修正在AI返回原始代码后“Skill”立即介入调用对应的代码格式化工具如Prettier、Black和静态分析工具如ESLint、Ruff对代码进行检查和修复。这一步不是简单的格式化它需要理解工具输出的错误和警告。智能反馈与迭代高级模式对于无法自动修复的复杂规范问题如复杂的命名建议、架构问题Skill可以将问题反馈给AI模型要求其根据规范描述重新生成或修正部分代码形成一个“生成-检查-修正-再生成”的微循环。最终交付将符合规范的、整洁的代码呈现给开发者或直接插入到编辑器中。2.2 技术方案选型考量实现上述思路有几种主流的技术路径各有优劣路径一IDE插件增强型这是最直接、体验最无缝的方式。例如在VSCode中你可以同时安装Copilot和Prettier、ESLint插件并确保保存时自动格式化。但这种方式下AI生成与规范检查是两个独立插件的先后行为缺乏协同。更高级的Skill可以是一个定制插件它劫持或包装了AI插件的代码输出在代码插入编辑器前就完成规范处理。优点用户体验好与开发环境深度集成。缺点依赖特定IDE功能受插件框架限制跨编辑器迁移成本高。路径二CLI工具封装型构建一个命令行工具比如叫ai-code。你通过这个工具来调用AI它内部的工作流程是调用AI API - 获取原始代码 - 调用格式化/检查工具 - 输出最终代码。这类似于一个智能的代码生成管道。优点编辑器无关灵活性强可以方便地集成到脚本、自动化流程中。缺点需要离开编辑器在终端操作可能打断工作流。路径三AI Agent集成型这是目前比较前沿的思路。你构建或使用一个具备“工具使用”Tool Use能力的AI Agent。这个Agent不仅拥有代码生成能力还被赋予了调用ESLint、Prettier等外部工具的能力。在你的指令中可以直接要求“请用Python写一个数据抓取函数并确保符合PEP 8规范使用Black格式化。” Agent在内部会先生成代码然后调用Black工具“执行”格式化最后将结果返回给你。像Claude Code、GPT-4等高级模型结合代码解释器Code Interpreter模式已经能初步实现这类操作。优点智能化程度高可以实现更复杂的规范理解和交互修正。缺点技术复杂度高依赖大模型的工具调用能力可能产生额外的API调用开销。路径四Git钩子补救型这是一种“最后防线”策略。在Git的pre-commit钩子中配置强大的Lint和格式化检查如Husky lint-staged。无论代码是AI写的还是人写的在提交前都必须通过规范检查否则无法提交。这强制保证了代码库的整洁。优点能保证仓库中代码的绝对规范是团队协作的黄金标准。缺点属于事后检查开发者本地可能仍有大量不规范代码反馈不够即时。对于个人开发者或小团队我推荐采用**“路径一基础版 路径四”的组合拳。即在IDE中配置好实时格式化同时在项目中配置强制的pre-commit钩子。而对于追求极致自动化体验的开发者可以尝试探索路径三**或基于路径二封装自己的自动化脚本。注意选择方案时务必考虑你主要使用的AI编程工具。如果深度依赖GitHub Copilot那么围绕VSCode或JetBrains IDE的插件生态进行增强是最佳选择。如果主要与ChatGPT、Claude的聊天界面交互那么一个能处理粘贴代码的CLI工具或浏览器插件可能更实用。3. 实战构建打造你的AI代码规范助手理论说得再多不如动手实现一个。下面我将以最通用、最灵活的**CLI工具封装型路径二**为例带你一步步构建一个简易但实用的AI代码规范Skill。我们将使用Python来实现因为它跨平台且拥有丰富的子进程和API调用库。3.1 环境准备与工具链确立首先确保你的开发环境已经就绪。我们需要两类工具代码处理工具和AI交互工具。1. 安装核心代码处理工具根据你的目标语言安装。这里以Python和TypeScript为例。# Python 环境 pip install black isort flake8 autoflake # black: 代码格式化 # isort: 导入排序 # flake8: 代码风格与静态检查 # autoflake: 自动移除未使用的导入和变量 # TypeScript/JavaScript 环境 (需要Node.js) npm install --save-dev prettier eslint # 或者全局安装 npm install -g prettier eslint2. 创建项目规范配置文件在你的项目根目录创建对应的配置文件这是“Skill”工作的依据。Python(pyproject.toml):[tool.black] line-length 88 target-version [py39] [tool.isort] profile black line_length 88TypeScript(.prettierrc):{ semi: true, trailingComma: es5, singleQuote: true, printWidth: 100, tabWidth: 2 }ESLint(.eslintrc.js): 根据你的框架如React、Vue进行配置这里给一个基础示例。module.exports { env: { browser: true, es2021: true }, extends: [eslint:recommended], parserOptions: { ecmaVersion: latest, sourceType: module }, rules: { no-unused-vars: warn, prefer-const: error }, };3. 准备AI交互能力我们将使用OpenAI的API作为示例。你需要一个API Key。pip install openai3.2 核心脚本开发ai_coder.py我们将创建一个Python脚本它主要做三件事1. 与AI对话获取代码2. 对代码进行规范化处理3. 输出最终结果。#!/usr/bin/env python3 AI代码规范助手 CLI 工具 用法python ai_coder.py --prompt 用Python写一个快速排序函数 import subprocess import sys import tempfile import os from pathlib import Path import argparse import openai # 或其他AI SDK # 配置你的AI API这里以OpenAI为例 # 请将你的API Key设置在环境变量OPENAI_API_KEY中或在此处直接配置不推荐 client openai.OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def get_code_from_ai(prompt, languagepython): 调用AI模型获取原始代码。 为了简化这里假设AI返回的是纯代码块。 实际应用中你需要解析AI返回的Markdown或JSON。 system_message fYou are a helpful coding assistant. Return only the {language} code block without any explanation, comments outside the code, or markdown backticks unless they are part of the code itself. try: response client.chat.completions.create( modelgpt-4-turbo-preview, # 或 gpt-3.5-turbo messages[ {role: system, content: system_message}, {role: user, content: prompt} ], temperature0.2, # 较低的温度使输出更确定、更规范 ) raw_code response.choices[0].message.content.strip() # 清理可能的markdown代码块标记 if raw_code.startswith(): lines raw_code.split(\n) raw_code \n.join(lines[1:-1]) if raw_code.endswith() else \n.join(lines[1:]) return raw_code except Exception as e: print(f调用AI API失败: {e}, filesys.stderr) sys.exit(1) def format_python_code(raw_code): 使用black和isort格式化Python代码 with tempfile.NamedTemporaryFile(modew, suffix.py, deleteFalse) as tmp: tmp.write(raw_code) tmp_path tmp.name try: # 1. 使用autoflake移除未使用的导入和变量 subprocess.run([autoflake, --in-place, --remove-all-unused-imports, --remove-unused-variables, tmp_path], checkTrue, capture_outputTrue) # 2. 使用isort排序导入 subprocess.run([isort, tmp_path], checkTrue, capture_outputTrue) # 3. 使用black格式化代码 subprocess.run([black, tmp_path], checkTrue, capture_outputTrue) # 4. 使用flake8进行检查只检查不修改 result subprocess.run([flake8, tmp_path], capture_outputTrue, textTrue) if result.returncode ! 0: print(代码风格检查发现以下问题已自动格式化但以下问题需手动注意, filesys.stderr) print(result.stdout, filesys.stderr) # 读取格式化后的代码 with open(tmp_path, r) as f: formatted_code f.read() finally: os.unlink(tmp_path) # 删除临时文件 return formatted_code def format_typescript_code(raw_code): 使用prettier格式化TypeScript/JavaScript代码 with tempfile.NamedTemporaryFile(modew, suffix.ts, deleteFalse) as tmp: tmp.write(raw_code) tmp_path tmp.name try: # 使用prettier格式化 subprocess.run([npx, prettier, --write, tmp_path], checkTrue, capture_outputTrue) # 这里可以添加eslint检查但注意有些规则可能需要手动修复 # result subprocess.run([npx, eslint, --fix, tmp_path], capture_outputTrue, textTrue) with open(tmp_path, r) as f: formatted_code f.read() finally: os.unlink(tmp_path) return formatted_code def main(): parser argparse.ArgumentParser(descriptionAI代码规范助手) parser.add_argument(--prompt, -p, requiredTrue, help给AI的代码生成提示词) parser.add_argument(--lang, -l, defaultpython, choices[python, typescript, javascript], help目标编程语言) parser.add_argument(--output, -o, help输出到文件不指定则打印到控制台) args parser.parse_args() print(f正在向AI请求生成 {args.lang} 代码..., filesys.stderr) raw_code get_code_from_ai(args.prompt, args.lang) print(原始代码获取成功开始规范化处理..., filesys.stderr) if args.lang python: final_code format_python_code(raw_code) elif args.lang in [typescript, javascript]: final_code format_typescript_code(raw_code) else: final_code raw_code # 其他语言暂不处理 if args.output: with open(args.output, w) as f: f.write(final_code) print(f规范化的代码已写入: {args.output}, filesys.stderr) else: print(\n *50 最终代码 *50) print(final_code) print(*110) if __name__ __main__: main()3.3 使用与效果演示保存上述脚本为ai_coder.py并赋予执行权限Linux/macOS:chmod x ai_coder.py。接下来进行测试。设置API Key:export OPENAI_API_KEYyour-api-key-here运行示例: 我们让AI生成一个有点“乱”的Python函数。python ai_coder.py --prompt 写一个python函数功能是读取一个json文件返回其中所有键的列表要处理文件不存在的情况 --lang pythonAI可能返回的原始代码模拟不规范:import json, os def get_keys_from_json(file_path): if os.path.exists(file_path): with open(file_path, r) as f: data json.load(f) keys list(data.keys()) return keys else: print(fFile {file_path} not found.) return [] unused_var 1这段代码存在几个问题import语句未排序和分组os.path.exists在打开文件前检查是冗余的open本身会抛出异常有一个未使用的变量unused_var且不符合Black的格式化风格。Skill处理后的输出: 经过我们的ai_coder.py处理后最终输出的代码将是import json import os def get_keys_from_json(file_path): try: with open(file_path) as f: data json.load(f) return list(data.keys()) except FileNotFoundError: print(fFile {file_path} not found.) return []可以看到Skill自动完成了以下工作移除了未使用的导入os因为os.path.exists被更优的异常处理替代。将import json, os拆分并排序为标准格式。用更优雅的try-except结构替换了冗余的文件存在性检查。移除了未使用的变量unused_var。应用了Black格式化如引号、缩进、空格。输出了一个更简洁、更符合PEP 8、更健壮的函数。实操心得这个脚本的关键在于临时文件的使用和子进程的链式调用。通过将AI生成的代码先写入临时文件我们可以方便地让各种命令行格式化工具对其操作最后再读回结果。这种设计使得工具链易于扩展如果你想加入对Go、Java等其他语言的支持只需添加对应的format_xxx_code函数即可。4. 高级技巧与集成方案基础的CLI工具已经能解决大部分问题但要将其打造成真正高效的“Skill”还需要考虑更深入的集成和优化。4.1 提示词工程让AI“更懂”规范与其在生成后修复不如让AI在一开始就生成更规范的代码。这需要通过系统提示词System Prompt和用户提示词User Prompt进行引导。在系统提示词中明确规范在调用AI API时系统消息可以设定AI的角色和规则。你是一个专业的Python开发助手。请严格遵守以下规范输出代码 1. 遵循PEP 8风格指南。 2. 使用Black格式化行宽88字符。 3. 使用isort排序导入。 4. 使用类型注解Type Hints。 5. 避免使用print进行调试使用日志。 6. 函数和变量名使用snake_case类名使用CamelCase。 请只返回代码块不要额外解释。在用户提示词中具体化要求差提示词“写个函数计算平均数。”好提示词“请用Python写一个函数calculate_mean接收一个数字列表numbers: List[float]作为参数返回一个float。使用类型注解并包含基本的输入验证如空列表处理。函数内部注释请用英文。”通过精心设计的提示词可以显著减少后续格式化工具的工作量甚至直接产出近乎完美的代码。4.2 与现有工作流深度集成1. VSCode任务Tasks集成在VSCode的.vscode/tasks.json中定义一个任务将我们的CLI工具与快捷键绑定。{ version: 2.0.0, tasks: [ { label: AI Generate Code, type: shell, command: python ${workspaceFolder}/ai_coder.py, args: [ --prompt, ${input:prompt}, --lang, ${input:language}, --output, ${file} ], problemMatcher: [] } ], inputs: [ { id: prompt, type: promptString, description: Enter your code generation prompt for AI }, { id: language, type: pickString, description: Select language, options: [python, typescript, javascript], default: python } ] }然后你可以通过VSCode的命令面板CtrlShiftP运行“Run Task” - “AI Generate Code”输入提示词它就会将生成的规范代码直接输出到当前激活的文件中。2. 封装为自定义的“Codeium”或“Copilot”风格插件思路这是一个更进阶的方案。你可以利用VSCode的扩展API开发一个自己的插件。这个插件在后台调用你的ai_coder.py脚本或者直接集成AI API和格式化逻辑。当用户通过某个快捷键或命令触发时插件可以 * 获取当前编辑器选中的文本作为提示词上下文。 * 弹出输入框让用户补充指令。 * 调用你的规范处理管道。 * 将处理好的代码直接插入编辑器或替换选区。 这种方式体验最接近原生Copilot但开发成本较高。3. 结合Git Hook作为终极守门员无论前面如何生成在提交代码时必须通过pre-commit钩子的检查。这是保证代码库清洁的“铁律”。你可以使用pre-commit框架轻松管理。# .pre-commit-config.yaml repos: - repo: https://github.com/psf/black rev: 23.12.1 hooks: - id: black language_version: python3.9 - repo: https://github.com/pycqa/isort rev: 5.13.2 hooks: - id: isort - repo: https://github.com/pycqa/flake8 rev: 7.0.0 hooks: - id: flake8这样即使AI生成的代码或你手动写的代码漏过了本地检查在git commit时也会被拦截并自动修复如果配置了--fix修复后需要重新git add和git commit。4.3 处理复杂场景与边界情况在实际使用中你会遇到一些挑战AI生成的是代码片段而非完整文件我们的格式化工具通常针对完整文件工作。对于片段可能需要将其包裹在一个临时的、最小的语法结构中如一个函数或类中再进行格式化格式化后再提取目标片段。这需要一些额外的文本处理逻辑。格式化工具与AI逻辑冲突有时AI生成的代码逻辑正确但格式化工具如Black的强制格式化可能会改变一些细微的语义例如长字符串的换行方式。这种情况下需要人工判断。我们的Skill应该能报告这些自动更改让开发者知晓。多语言混合项目一个项目可能同时包含Python、TypeScript、SQL等。我们的Skill需要能根据文件后缀名或用户指定自动路由到正确的格式化工具链。可以在CLI工具中增加一个--file参数根据文件后缀自动判断语言。性能考量频繁调用AI API和外部格式化工具可能带来延迟。对于即时性要求高的场景如IDE实时补全可以考虑将部分规则如简单的命名转换、缩进修正用纯Python/JavaScript实现减少进程启动开销或者对格式化结果进行缓存。5. 避坑指南与经验实录在开发和使用的过程中我踩过不少坑也总结了一些让这个“Skill”更好用的经验。5.1 常见问题与排查问题现象可能原因解决方案运行脚本报错ModuleNotFoundError依赖的格式化工具如black, isort未安装或不在PATH中。1. 使用pip list或npm list -g检查工具是否安装。2. 确保使用虚拟环境venv/conda时脚本在该环境中运行。3. 对于全局安装的npm包尝试使用npx前缀如npx prettier。格式化后代码语法错误1. AI生成的原始代码本身有语法错误。2. 格式化工具版本与配置不兼容。3. 临时文件处理过程中编码错误。1. 先输出原始代码检查其正确性。2. 确保项目中的配置文件如pyproject.toml与格式化工具版本匹配。3. 在脚本中增加原始代码的语法验证步骤如python -m py_compile。AI返回的不是纯代码AI的回复可能包含解释性文字、Markdown代码块标记。在get_code_from_ai函数中加强文本清洗逻辑使用更精确的正则表达式如r(?:\w)?\n([\s\S]*?)\n来提取代码块。处理速度慢1. AI API调用网络延迟。2. 频繁启动子进程开销大。1. 考虑使用异步请求asyncioaiohttp。2. 对于小型、频繁的修正可以调研是否能用对应的语言库如Python的black库、isort库进行程序化调用避免启动进程。与团队规范不一致本地配置的格式化规则与团队项目的配置不同。核心原则Skill的规范配置必须与项目根目录的配置文件同步。让脚本自动读取项目中的配置文件而不是使用一套全局默认配置。5.2 提升效能的独家技巧分层提示策略不要每次都发送完整的、冗长的系统提示词。可以建立一个“提示词模板库”。对于简单的代码补全使用轻量级提示词对于需要生成完整模块或复杂逻辑时再使用包含完整规范的重型提示词。这可以减少API的token消耗提升响应速度。本地轻量模型备用对于简单的代码风格转换如命名风格转换、添加基础类型注解可以考虑使用在本地运行的、较小的代码模型如通过Ollama运行的CodeLlama系列。虽然能力不如GPT-4但对于规则明确的格式化任务可能更快、更便宜。我们的Skill可以设计一个降级策略先尝试用本地模型快速修正如果不行再调用大模型或进行传统格式化。结果缓存与复用对于常见的、模式化的代码生成请求例如“创建一个React函数组件”可以将AI生成并规范化后的结果进行缓存基于提示词和参数的哈希值。下次遇到相同或相似的请求时直接返回缓存结果极大提升体验。这在开发中有大量重复模式代码时效果显著。“学习”团队模式更高级的Skill可以分析项目历史代码库自动总结出团队的编码习惯如常用的工具函数命名、特定的错误处理模式并将这些模式融入到给AI的提示词中或者作为后处理规则使AI生成的代码不仅“规范”而且“像我们团队写的”。构建这样一个AI代码规范Skill本质上是在建立一套人机协作的新契约。它要求我们不仅要把AI当作一个代码生成器更要把它看作一个需要被引导和训练的初级合作伙伴。通过将规范检查从“事后”提到“事中”甚至“事前”我们最终收获的不仅仅是整洁的代码更是一个高效、可控、可持续的智能编程工作流。这个过程本身也是对我们自身编码规范的一次重新审视和固化。