103 lines (80 loc) · 2.27 KB

AGENTS.md

目标

本项目是 Python CLI 工具。
你在修改或新增代码时，必须优先保证：

可读性高于炫技
小文件、小函数、低耦合
命令层、业务层、基础设施层分离
先能维护，再谈扩展
不要把整个 CLI 写成一个巨型单文件

技术栈约束

Python 版本

使用 Python 3.11+
优先使用标准库
必要时再引入第三方库
CLI 优先使用：
- typer：适合现代 CLI，类型提示友好
- 或 click：若项目已使用 click，则保持一致
配置与数据结构优先使用：
- dataclasses
- typing
- 必要时使用 pydantic

总体编码原则

1. 代码风格

遵循 PEP 8
全量类型注解
函数、类、模块名要表意明确
禁止出现模糊命名：
- data
- obj
- tmp
- misc
- handle_stuff
优先写清晰代码，不要为了“高级感”滥用抽象

2. 单一职责

一个模块只做一类事
一个函数只做一件事
一个类只承担一个主要角色
CLI 参数解析、业务处理、文件读写、网络请求必须拆开

3. 显式优于隐式

输入输出要清晰
错误要显式处理
不要偷偷修改全局状态
不要依赖隐藏副作用

4. 可测试

业务逻辑不要直接写死在 CLI 命令函数里
CLI 层只负责：
- 接收参数
- 调用 service
- 输出结果
- 处理退出码

文件和函数规模限制

单个 Python /markdown 文件最大行数

硬性要求：

理想行数：200~300 行
警戒线：400 行
硬上限：500 行

超过 400 行时，默认认为职责已经开始混乱，必须评估拆分。
超过 500 行时，必须拆分，不要继续堆。

统计时不必过度纠结空行和纯注释，但不能靠大量空行规避限制。

单个函数最大行数

理想：20~40 行
警戒线：60 行
硬上限：80 行

超过 60 行时优先拆分。
超过 80 行时必须拆。

单个类最大行数

理想：100~200 行
警戒线：250 行
硬上限：300 行

如果一个类同时在做：

参数处理
业务编排
网络请求
数据转换
输出格式化

那么这个类设计就是失败的，必须拆分。