awesome-rules

name: "awesome-rules" description: "Continue.dev 编程基础规则合集（基础：代码规范、中文注释、不啰嗦）。触发条件：代码编写规范、命名约定、函数设计、注释规范、代码整洁、SOLID原则、错误处理。"

Continue.dev Awesome Rules 合集

核心原则：本Skill整合 continuedev/awesome-rules 仓库的核心编程基础规范，包含代码规范、注释规范、代码整洁三大模块。

使用对象：需要统一编码风格、规范注释、保持代码整洁的AI模型。

强制要求：编写代码时严格遵循命名规范、函数设计原则、注释规范，不自行发明风格。如需编写测试脚本或使用截图功能，一律保存到 test/ 目录。

触发条件

以下任一关键词或场景出现时，自动启用本Skill：

非触发场景（不启用本Skill）：

• 非编程类任务
• 纯架构设计讨论
• 排错调试（此时应启用 mattpocock-skills）

模块一：代码规范（Coding Standards）

来源：continuedev/awesome-rules - coding-standards

命名规范

• 使用描述性和有意义的名称
• 保持命名模式一致
• 避免缩写和单字母（循环计数器除外）
• 使用可搜索的常量名
• 从名称就能看清用途

# 好
MAX_RETRY_ATTEMPTS = 3
user_authentication_token = generate_token()
def calculate_compound_interest(principal, rate, time): ...

# 不好
max = 3
tkn = generate_token()
def calc(p, r, t): ...

函数设计

• 保持函数小而专注（单一职责）
• 限制函数参数（理想3个或更少）
• 使用描述性的函数名，表明动作
• 尽量避免副作用
• 提前返回以减少嵌套

# 好
def calculate_order_total(items):
    if not items:
        return Decimal('0.00')
    subtotal = sum(item.price * item.quantity for item in items)
    return apply_taxes(subtotal)

# 不好
def process(data):
    # 200行的混合逻辑
    # 多个职责
    # 隐藏的副作用

代码组织

project/
├── src/
│   ├── controllers/
│   ├── services/
│   ├── models/
│   ├── utils/
│   └── config/
├── tests/
├── docs/
└── scripts/

错误预防

• 在边界处验证输入
• 尽量使用类型系统
• 显式处理边缘情况
• 快速失败，错误信息清晰
• 使用防御性编程

def divide_numbers(dividend, divisor):
    if divisor == 0:
        raise ValueError('除数不能为零')
    if not isinstance(dividend, (int, float)):
        raise TypeError('被除数必须是数字')
    return dividend / divisor

DRY原则

• 不重复自己
• 提取公共功能
• 用配置替代重复
• 创建可复用组件
• 在DRY和清晰度之间平衡

SOLID原则

模块二：注释规范（Code Comments）

来源：continuedev/awesome-rules - code-comments

何时写注释

• 解释为什么，而不是什么
• 记录复杂的业务逻辑或算法
• 澄清不明显的实现
• 警告潜在的陷阱或副作用
• 为未来的维护者提供上下文

好注释示例

# 使用指数退避避免高峰时段压倒API
# （参见事故报告 #1234）
delay = min(1000 * pow(2, retry_count), 30000)

# WORKAROUND: Chrome bug #123456 需要显式设置高度
# Chrome 120+ 采用率达95%后移除
element.style.height = 'auto'

# TODO(john): 实现网络失败的重试逻辑
# TODO(security): v2.0 发布前添加限流
# FIXME: 处理用户有多个账户时的边缘情况
# HACK: 临时修复，数据库迁移完成后移除

坏注释示例

# 不好：显而易见的注释
# 计数器加1
counter += 1

# 不好：过时的注释
# 给用户发邮件（实际上现在发的是短信）
await notification_service.send(user)

# 不好：无上下文的注释掉的代码
# user.set_status('active')
# user.save()

Python文档字符串规范

def process_transaction(transaction):
    """
    处理金融交易，包含欺诈检测和验证。

    此方法在执行前进行多项检查：
    1. 验证交易格式和必填字段
    2. 检查欺诈检测规则
    3. 验证账户余额和限额
    4. 通过支付网关处理

    Args:
        transaction: 包含支付细节的交易对象

    Returns:
        ProcessResult，包含状态和错误信息

    Raises:
        ValidationError: 交易格式无效时
        InsufficientFundsError: 账户余额不足时

    Note:
        超过$10,000的交易需要额外验证
    """

最佳实践

• 注释保持简洁和相关
• 代码变更时同步更新注释
• 整个代码库保持一致的注释风格
• 写中文注释（本项目要求）
• 代码审查时也审查注释

模块三：代码整洁（Clean Code）

来源：continuedev/awesome-rules - clean-code

单一职责检查

评估每个类/函数：

• 是否有单一明确定义的用途？
• 不同关注点是否适当分离？
• 更改系统的一个方面是否需要修改多个组件？

警告信号：

• 上帝类，什么都能做
• 方法名含"并"(and/or)，说明做了多件事
• 业务逻辑与UI代码混合
• 数据访问与业务规则混合

SOLID实现指南

单一职责原则（SRP）：

• 每个类只能有一个改变理由
• 类超过100-150行时，考虑是否有多个职责
• 将横切关注点（日志、验证、错误处理）与业务逻辑分离

开闭原则（OCP）：

• 设计类使其可扩展而不修改
• 用抽象类和接口定义稳定契约
• 用策略模式替代条件逻辑

里氏替换原则（LSP）：

• 派生类必须完全可替换其基类
• 不要在子类中加强前置条件
• 不要在子类中削弱后置条件

接口隔离原则（ISP）：

• 创建专注、最小化的接口
• 避免"胖"接口，强制客户端依赖不使用的方法
• 用角色接口表示行为，而非对象类型

依赖反转原则（DIP）：

• 高层模块依赖抽象，而非具体实现
• 所有依赖显式化，通过构造函数参数注入
• 针对接口编程，不针对具体类编程

优先级规则

1. 编写新代码 → 优先用模块一（代码规范）约定命名和结构
2. 添加注释 → 优先用模块二（注释规范）写中文注释
3. 代码审查/重构 → 优先用模块三（代码整洁）检查质量
4. 多个场景叠加 → 三个模块同时生效，顺序执行