让AI生成的代码更易于审查和维护 AI生成的代码往往第一次就能运行，但结构可能难以理解。你可能会看到冗长的函数、重复的逻辑、模糊的名称或深层嵌套的条件语句，这些都会拖慢未来的修改速度。Clean Code Skills 为你的AI代理提供基于 Robert C. Martin 的《Clean Code》原则（适用于 Python 和 TypeScript）的集中指导。每项技能针对一个维护问题：
• boy-scout：改善它所触碰的代码
• clean-functions：保持函数短小且专注
• clean-names：选择能解释意图的名称
• clean-tests：围绕明确的行为编写测试
• clean-general：减少重复、魔法数字、长分支路径等

我在要求代理编写Python代码、重构现有代码、审查更改或添加测试时使用此项技能。
仓库链接：https://github.com/ertugrul-dmr/clean-code-skills
… #AI #CleanCode #Python #软件工程

ertugrul-dmr/clean-code-skills

来源：https://github.com/ertugrul-dmr/clean-code-skills

AI代理的Clean Code技能

Agent Skills (https://agentskills.io)
许可证：MIT

教会你的AI写出不烂的代码。

本仓库包含 Agent Skills (https://agentskills.io)，用于强制实施 Robert C. Martin 的 Clean Code 原则。它们与 Google Antigravity、Anthropic Claude Code 以及任何支持 Agent Skills 标准的代理兼容。

为什么？

AI 生成代码很快，但研究表明它也会快速产生技术债务：

• GitClear：采用AI后代码重复率增加4倍
• Carnegie Mellon：采用Cursor后静态分析警告增加30%，代码复杂度增加41%
• Google DORA：AI采用与软件交付稳定性呈负相关

这些技能将经过实战检验的解决方案直接编码到AI工作流中，恰好解决上述问题。

包含内容

使用主技能进行全面覆盖，或使用单个技能进行针对性实施。

选择你的语言

选择一个语言分支，只复制该分支的技能：

每个技能目录只能安装一个语言分支。Python 和 TypeScript 分支重复使用相同的技能名称（boy-scout、clean-functions 等）。同时安装两者会导致代理加载冲突指令，行为不一致。

# Python 分支  
cp -r skills/python/* /  

# TypeScript 分支  
cp -r skills/typescript/* /  

童子军规则

boy-scout 技能体现了 Clean Code 的核心理念：

“总是让模块比你签出时更整洁地签入。”

你不必让代码完美——只需每次触碰时 稍微好一点点。
boy-scout 技能编排其他技能，确保每次代码交互都留下一连串的小改进。

安装

每个目标目录（.agent/skills、.claude/skills、~/.claude/skills 等）只安装一个语言分支。

Google Antigravity

项目专属（仅应用于一个项目）：

# 从项目根目录执行  
mkdir -p .agent/skills  

# Python 分支  
cp -r skills/python/* .agent/skills/  

# TypeScript 分支  
cp -r skills/typescript/* .agent/skills/  

全局（应用于所有项目）：

mkdir -p ~/.gemini/antigravity/skills  

# Python 分支  
cp -r skills/python/* ~/.gemini/antigravity/skills/  

# TypeScript 分支  
cp -r skills/typescript/* ~/.gemini/antigravity/skills/  

快速安装（全局，单条命令）——选择一个分支：

# Python 分支  
git clone https://github.com/ertugrul-dmr/clean-code-skills.git /tmp/clean-code-skills && \  
mkdir -p ~/.gemini/antigravity/skills && \  
cp -r /tmp/clean-code-skills/skills/python/* ~/.gemini/antigravity/skills/ && \  
rm -rf /tmp/clean-code-skills  

# TypeScript 分支  
git clone https://github.com/ertugrul-dmr/clean-code-skills.git /tmp/clean-code-skills && \  
mkdir -p ~/.gemini/antigravity/skills && \  
cp -r /tmp/clean-code-skills/skills/typescript/* ~/.gemini/antigravity/skills/ && \  
rm -rf /tmp/clean-code-skills  

Anthropic Claude Code

项目专属：

# 从项目根目录执行  
mkdir -p .claude/skills  

# Python 分支  
cp -r skills/python/* .claude/skills/  

# TypeScript 分支  
cp -r skills/typescript/* .claude/skills/  

全局：

mkdir -p ~/.claude/skills  

# Python 分支  
cp -r skills/python/* ~/.claude/skills/  

# TypeScript 分支  
cp -r skills/typescript/* ~/.claude/skills/  

快速安装（全局，单条命令）——选择一个分支：

# Python 分支  
git clone https://github.com/ertugrul-dmr/clean-code-skills.git /tmp/clean-code-skills && \  
mkdir -p ~/.claude/skills && \  
cp -r /tmp/clean-code-skills/skills/python/* ~/.claude/skills/ && \  
rm -rf /tmp/clean-code-skills  

# TypeScript 分支  
git clone https://github.com/ertugrul-dmr/clean-code-skills.git /tmp/clean-code-skills && \  
mkdir -p ~/.claude/skills && \  
cp -r /tmp/clean-code-skills/skills/typescript/* ~/.claude/skills/ && \  
rm -rf /tmp/clean-code-skills  

验证

在运行中的 Claude Code 会话中，确认技能已加载：

• 询问 What skills are available?——你应该会看到 boy-scout、clean-comments、clean-functions、clean-general、clean-names、clean-tests 和 python-clean-code 在列表中。
• 或者直接调用其中一个：/boy-scout 应显式加载童子军技能。

技能会在现有的 ~/.claude/skills/ 目录内热重载——无需重启。如果你是在本次会话中首次创建该目录，请重启一次 Claude Code，使其开始监听该目录。

更新

重新运行快速安装命令以拉取最新版本。它将覆盖七个技能目录，其他技能不受影响。

如果你预计会经常更新，建议使用符号链接而非复制：

git clone https://github.com/ertugrul-dmr/clean-code-skills.git ~/src/clean-code-skills  

# 选择一个分支——将 `python` 替换为 `typescript` 以使用 TS 分支。  
cd ~/src/clean-code-skills/skills/python  
for d in */; do ln -sfn "$PWD/${d%/}" "$HOME/.claude/skills/${d%/}"; done  

然后在 ~/src/clean-code-skills 中执行 git pull 即可刷新所有技能。

卸载

rm -rf ~/.claude/skills/{boy-scout,clean-comments,clean-functions,clean-general,clean-names,clean-tests,python-clean-code}  

其他兼容 Agent Skills 的工具

这些技能遵循 Agent Skills (https://agentskills.io) 开放标准。请查看你的工具文档以了解技能目录位置，然后将 skills/ 文件夹的内容复制到该目录。

使用方式

安装后，技能会根据上下文自动激活。请你的代理：

• 编写代码：“创建一个用户认证模块” → 技能强制实施整洁模式
• 审查代码：“审查此函数是否有问题” → 代理按规则编号识别违规
• 重构：“重构此代码使其更整洁” → 代理应用所有相关规则

示例

之前（违反10条规则）：

from utils import * # P1  
# Author: John, Modified: 2024-01-15 # C1  
def proc(d, t, flag=False): # N1, F1, F3  
    # Process the data # C3  
    x = [] # N1  
    for i in d:  
        if flag: # F3  
            if i['type'] == 'A': # G23  
                x.append(i['val'] * 1.0825) # G25  
            elif i['type'] == 'B':  
                x.append(i['val'] * 1.05) # G25  
            else:  
                x.append(i['val'])  
    return x  

之后（技能激活时）：

import json  
from dataclasses import dataclass  
from typing import Literal  

TAX_RATE_CA = 0.0825  
TAX_RATE_NY = 0.05  

TransactionType = Literal['CA', 'NY']  

@dataclass  
class Transaction:  
    value: float  
    type: TransactionType  

def apply_tax(transaction: Transaction) -> float:  
    """Apply state-specific tax to transaction value."""  
    tax_rates = {'CA': TAX_RATE_CA, 'NY': TAX_RATE_NY}  
    return transaction.value * (1 + tax_rates[transaction.type])  

def process_transactions_with_tax(transactions: list[Transaction]) -> list[float]:  
    """Calculate taxed values for all transactions."""  
    return [apply_tax(t) for t in transactions]  

def process_transactions_without_tax(transactions: list[Transaction]) -> list[float]:  
    """Extract raw values from all transactions."""  
    return [t.value for t in transactions]  

之后（TypeScript 分支）：

type TransactionType = "CA" | "NY"  

const TAX_RATE_CA = 0.0825  
const TAX_RATE_NY = 0.05  

type Transaction = {  
  value: number  
  type: TransactionType  
}  

function applyTax(transaction: Transaction): number {  
  const taxRates: Record<TransactionType, number> = {  
    CA: TAX_RATE_CA,  
    NY: TAX_RATE_NY,  
  }  
  return transaction.value * (1 + taxRates[transaction.type])  
}  

function processTransactionsWithTax(transactions: Transaction[]): number[] {  
  return transactions.map(applyTax)  
}  

function processTransactionsWithoutTax(transactions: Transaction[]): number[] {  
  return transactions.map((transaction) => transaction.value)  
}  

规则参考

注释 (C1-C5)

函数 (F1-F4)

通用 (G1-G36)

命名 (N1-N7)

Python 专属 (P1-P3)

TypeScript 专属 (TS1-TS3)

测试 (T1-T9)

自定义

使用单项技能

不需要全部66条规则？只复制你需要的技能：

# 仅函数规则  
cp -r skills/python/clean-functions ~/.gemini/antigravity/skills/  

# 仅注释规则  
cp -r skills/typescript/clean-comments ~/.claude/skills/  

扩展技能

通过编辑 SKILL.md 文件或创建新的技能文件夹来添加你自己的规则：

skills/  
├── python/  
│   ├── python-clean-code/  
│   │   └── SKILL.md  
│   └── clean-comments/  
│       └── SKILL.md  
├── typescript/  
│   ├── typescript-clean-code/  
│   │   └── SKILL.md  
│   └── clean-comments/  
│       └── SKILL.md  
└── my-team-standards/   # 你的自定义技能  
    └── SKILL.md  

添加实施脚本（可选）

本仓库默认不附带 scripts/ 文件夹或 lint 脚本。如果你想要更严格的实施，请在技能文件夹内创建你自己的脚本。

skills/python/python-clean-code/  
├── SKILL.md  
└── scripts/  
    └── lint.py  

技能如何工作

技能使用渐进式披露：

1. 发现：代理只看到技能名称和描述
2. 激活：当你的请求匹配某个描述时，加载完整的指令
3. 执行：仅在需要时加载脚本和模板

这能让代理保持快速——当你在编写 React 组件时，它不会想着数据库迁移。

贡献

欢迎提交 PR！一些想法：

• 随着规则演变保持 Python/TypeScript 对等
• 额外的语言支持（Go、Rust）
• 集成测试
• 预提交钩子
• IDE 扩展

资源

• Clean Code (https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) by Robert C. Martin
• Agent Skills Standard (https://agentskills.io)
• Antigravity Documentation (https://developers.google.com/antigravity)
• Claude Code Documentation (https://docs.anthropic.com/claude-code)

许可证

MIT 许可证。详见 LICENSE。

编程的未来是人类意图由 AI 翻译。确保翻译在保留质量的同时，不仅仅是速度。