Claude-skill-registry code-style

代码风格规范 / Code style conventions。在编写、编辑、评审 Python 代码时使用。包括类型注解、Decimal 精度、Docstring、模块组织等规范。Use when writing, editing, or reviewing Python code. Enforces type hints, Decimal precision, docstrings, and module organization.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/code-style" ~/.claude/skills/majiayu000-claude-skill-registry-code-style-6e8438 && rm -rf "$T"

manifest: skills/data/code-style/SKILL.md

Python code style for fund-portfolio-bot

本 Skill 强调编码规范中最关键、最容易被忽略的规则。

完整编码规范见
CLAUDE.md
第 3 节（核心约束）。分层架构约束见
.claude/skills/architecture/SKILL.md
。

When to use

在以下场景使用本 Skill（触发词：代码风格、类型注解、Docstring、精度、code style、type hints、docstring）：

生成新的 Python 模块（尤其是
```
src/
```
下）
修改现有函数或类
做代码重构或代码评审
用户提到"类型注解"、"Decimal"、"文档"、"代码规范"时

类型与数值正确性

所有函数参数与返回值都应添加类型注解。
优先使用现代类型语法：
- ```
list[str]
```
  ,
```
dict[str, Decimal]
```
  ,
```
X | None
```
- 避免使用
```
List
```
  /
```
Optional
```
  等老式写法，除非项目已有统一约定。
金额、净值、份额等金融相关字段一律使用
```
Decimal
```
。
不要使用
```
float
```
做任何金融计算。

Docstring 与注释

公开的类与函数应该有简洁的中文 docstring，说明：
- 主要职责
- 关键业务约束或注意点
Docstring 不需要重复类型信息（类型以注解为准）。
数字标签注释（CLI 层规范）：
- 函数内部用
```
# 1.
```
```
# 2.
```
```
# 3.
```
  标记逻辑步骤
- 示例：
```
# 1. 解析参数
```
  →
```
# 2. 调用 Flow
```
  →
```
# 3. 格式化输出
```
注释只在业务规则不直观时补充解释，避免噪音注释。

模块与类内部结构

原则：入口在上，工具在下；公开在上，私有在下。

类内部顺序：

```
__init__
```
公共方法
以
```
_
```
开头的私有辅助方法

模块内部顺序：

import（按标准库 / 第三方 / 本地分组）
公共类与公共函数
仅模块内部使用的私有工具函数（例如
```
_helper_*
```
）

命名惯例

状态类字段或枚举值用小写字符串，例如：
- ```
"normal"
```
  ,
```
"delayed"
```
  ,
```
"pending"
```
文件名、函数名、变量名：
```
snake_case
```
类名：
```
PascalCase
```
CLI 层函数命名（v0.4.2+ 统一规范）：
- ```
_parse_args()
```
  ：参数解析函数
- ```
_format_*()
```
  ：格式化输出辅助函数（如
```
_format_result()
```
  ,
```
_format_fees()
```
  ）
- ```
_do_*()
```
  ：命令执行函数（如
```
_do_buy()
```
  ,
```
_do_list()
```
  ,
```
_do_confirm()
```
  ）
- ```
main()
```
  ：CLI 主入口，只做路由

分层与配置相关约束

```
core
```
层代码不要从
```
adapters
```
或
```
app
```
导入。
业务逻辑中避免直接使用
```
os.getenv
```
：
- 优先通过已有的配置模块或适配层获取配置。

DCA & AI 分工命名规范

本项目是 AI 驱动 的投资工具。在 DCA、历史扫描、AI 分析相关代码中，严格遵循 "规则算事实，AI 做解释" 的分工原则，通过命名来强化这个边界。

规则层数据模型

规则层只输出可重算的结构化事实，严禁直接生成主观结论。

后缀	定义	模块内示例	跨模块示例
`*Facts`	结构化事实快照（日期、金额、间隔等）	`Facts`	`DcaFacts`
`*Check`	规则验证结果（命中+偏差+说明）	`Check`	`DayCheck`
`*Flag`	异常标记（不下结论，仅标记）	`Flag`	`Flag`
`*Draft`	建议方案（不入库，内存结构）	`Draft`	`PlanDraft`
`*Result`	内部中间聚合（如回填结果）	`Result`	`BackfillResult`
`*Report`	CLI/AI 展示用报告	`Report`	`ScanReport`

简化原则：模块路径已包含领域信息时，可省略前缀；跨模块导出时保留上下文。

Flow 函数动词

动词	约束	模块内示例	跨模块示例
`build_*()`	只读计算，返回 `*Facts`	`build_facts()`	`build_dca_facts()` (批次为参数)
`scan_*()`	只读无副作用（幂等）	`scan()`	`scan_trading_history()`
`draft_*()`	返回 `*Draft` ，不入库	`draft()`	`draft_dca_plan()`
`backfill_*()`	写操作，修改数据库	`backfill()`	`backfill_dca()` (不需要 for_batch)

关键原则：

看到
```
scan_
```
/
```
build_
```
/
```
draft_
```
就知道安全可调（只读）
看到
```
backfill_
```
就要警惕会修改数据库
参数而非函数名来表达"对什么"（batch_id, fund_code 等是参数）

AI 层（预留）

AI 基于规则层的

*Facts

生成语义解释，仅写入解释性字段，不修改核心数据。

```
*Insight
```
：洞察（如"这笔交易可能是限额"）
```
*Explanation
```
：自然语言解释
```
*Label
```
：分类标签

提交前检查

在可能的情况下：

运行静态检查（例如项目中配置的
```
ruff check --fix .
```
）。
快速浏览本次 diff，确认：
- 风格清理没有改变业务行为
- 没有遗留调试代码（例如
```
print
```
  、
```
breakpoint()
```
  ）。