// 代码风格规范 / Code style conventions。在编写、编辑、评审 Python 代码时使用。包括类型注解、Decimal 精度、Docstring、模块组织等规范。Use when writing, editing, or reviewing Python code. Enforces type hints, Decimal precision, docstrings, and module organization.
项目架构约定：通过 Root/Folder/File 三层极简元数据（_dir.md + I/O/Pos 注释） 让 AI 在任意位置自定位。 **AI 创建文件夹时自动触发**：hook 会生成 _dir.md 模板，AI 填写 Input/Output/Pos。
在编写、更新、维护 roadmap.md 的时候触发
多模型协作 — 调用 gemini-agent 和 codex-agent 辅助分析 **触发场景**（主动使用）： - 深度代码分析：算法理解、性能瓶颈、架构梳理 - 大范围探索：5+ 文件、模块依赖、调用链追踪 - 复杂推理：方案评估、逻辑验证、并发安全分析 - 多视角决策：需要不同角度分析再综合判断 **不触发**： - 简单修改（1-2 文件的明确改动） - 文件查找（用 Explore 或 Glob/Grep） - 已知路径的读写操作 **核心原则**：你是决策者和执行者，外部模型是顾问。
分层架构规范 / Architecture and layering rules (v0.3.1)。在设计新组件、修改导入、检查分层时使用。核心约束：cli → flows → data，core 向内不向外。Use when designing components, changing imports, or reviewing layering decisions. Enforces cli/flows/core/data separation.
命名规范 / Naming conventions。在创建类、函数、变量，或重命名、检查命名时使用。核心原则：简洁优先，上下文消歧义，类型提示已提供足够信息。Use when naming classes/functions/variables, renaming code, or reviewing names. Prioritizes brevity over self-documentation.
用于梳理和可视化代码流程，生成清晰的 ASCII 流程图、数据流图和表格分析。适用于已有代码的梳理、新功能设计的说明、以及技术文档的编写。
| name | code-style |
| description | 代码风格规范 / Code style conventions。在编写、编辑、评审 Python 代码时使用。包括类型注解、Decimal 精度、Docstring、模块组织等规范。Use when writing, editing, or reviewing Python code. Enforces type hints, Decimal precision, docstrings, and module organization. |
本 Skill 强调编码规范中最关键、最容易被忽略的规则。
完整编码规范见
CLAUDE.md第 3 节（核心约束）。 分层架构约束见.claude/skills/architecture/SKILL.md。
在以下场景使用本 Skill（触发词：代码风格、类型注解、Docstring、精度、code style、type hints、docstring）：
src/ 下）list[str], dict[str, Decimal], X | NoneList / Optional 等老式写法，除非项目已有统一约定。Decimal。float 做任何金融计算。# 1. # 2. # 3. 标记逻辑步骤# 1. 解析参数 → # 2. 调用 Flow → # 3. 格式化输出原则：入口在上，工具在下；公开在上，私有在下。
类内部顺序：
__init___ 开头的私有辅助方法模块内部顺序：
_helper_*）"normal", "delayed", "pending"snake_casePascalCase_parse_args()：参数解析函数_format_*()：格式化输出辅助函数（如 _format_result(), _format_fees()）_do_*()：命令执行函数（如 _do_buy(), _do_list(), _do_confirm()）main()：CLI 主入口，只做路由core 层代码不要从 adapters 或 app 导入。os.getenv：
本项目是 AI 驱动 的投资工具。在 DCA、历史扫描、AI 分析相关代码中，严格遵循 "规则算事实，AI 做解释" 的分工原则，通过命名来强化这个边界。
规则层只输出可重算的结构化事实，严禁直接生成主观结论。
| 后缀 | 定义 | 模块内示例 | 跨模块示例 |
|---|---|---|---|
*Facts | 结构化事实快照（日期、金额、间隔等） | Facts | DcaFacts |
*Check | 规则验证结果（命中+偏差+说明） | Check | DayCheck |
*Flag | 异常标记（不下结论，仅标记） | Flag | Flag |
*Draft | 建议方案（不入库，内存结构） | Draft | PlanDraft |
*Result | 内部中间聚合（如回填结果） | Result | BackfillResult |
*Report | CLI/AI 展示用报告 | Report | ScanReport |
简化原则：模块路径已包含领域信息时，可省略前缀；跨模块导出时保留上下文。
| 动词 | 约束 | 模块内示例 | 跨模块示例 |
|---|---|---|---|
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_ 就要警惕会修改数据库AI 基于规则层的 *Facts 生成语义解释，仅写入解释性字段，不修改核心数据。
*Insight：洞察（如"这笔交易可能是限额"）*Explanation：自然语言解释*Label：分类标签在可能的情况下：
ruff check --fix .）。print、breakpoint()）。