Python code style for fund-portfolio-bot

This Skill emphasizes the most critical and easily overlooked rules in coding conventions.

See Section 3 (Core Constraints) of
CLAUDE.md
for the complete coding conventions. See
.claude/skills/architecture/SKILL.md
for layered architecture constraints.

When to use

Use this Skill in the following scenarios (trigger words: code style, type hints, docstring, precision, code style, type hints, docstring):

Generating new Python modules (especially under
```
src/
```
)
Modifying existing functions or classes
Conducting code refactoring or code reviews
When users mention "type hints", "Decimal", "documentation", or "code conventions"

Type and Numeric Correctness

All function parameters and return values should have type hints added.
Prefer modern type syntax:
- ```
list[str]
```
  ,
```
dict[str, Decimal]
```
  ,
```
X | None
```
- Avoid outdated syntax like
```
List
```
  /
```
Optional
```
  unless there is an existing unified convention in the project.
Financial-related fields such as amount, net value, and shares must use
```
Decimal
```
.
Do not use
```
float
```
for any financial calculations.

Docstring and Comments

Public classes and functions should have concise Chinese docstrings explaining:
- Main responsibilities
- Key business constraints or considerations
Docstrings do not need to repeat type information (types are based on annotations).
Numbered Tag Comments (CLI layer convention):
- Mark logical steps inside functions with
```
# 1.
```
```
# 2.
```
```
# 3.
```
- Example:
```
# 1. Parse parameters
```
  →
```
# 2. Call Flow
```
  →
```
# 3. Format output
```
Only add comments to explain non-intuitive business rules; avoid noisy comments.

Module and Class Internal Structure

Principle: Entry points at the top, utilities at the bottom; public members at the top, private members at the bottom.

Class internal order:

```
__init__
```
Public methods
Private helper methods starting with
```
_
```

Module internal order:

Imports (grouped by standard library / third-party / local)
Public classes and public functions
Private utility functions only used within the module (e.g.,
```
_helper_*
```
)

Naming Conventions

State class fields or enum values use lowercase strings, e.g.:
- ```
"normal"
```
  ,
```
"delayed"
```
  ,
```
"pending"
```
File names, function names, variable names:
```
snake_case
```
Class names:
```
PascalCase
```
CLI Layer Function Naming (unified convention for v0.4.2+):
- ```
_parse_args()
```
  : Parameter parsing function
- ```
_format_*()
```
  : Output formatting helper functions (e.g.,
```
_format_result()
```
  ,
```
_format_fees()
```
  )
- ```
_do_*()
```
  : Command execution functions (e.g.,
```
_do_buy()
```
  ,
```
_do_list()
```
  ,
```
_do_confirm()
```
  )
- ```
main()
```
  : CLI main entry point, only handles routing

Layered and Configuration-related Constraints

Code in the
```
core
```
layer should not import from
```
adapters
```
or
```
app
```
.
Avoid direct use of
```
os.getenv
```
in business logic:
- Prioritize obtaining configurations through existing configuration modules or adaptation layers.

DCA & AI Division of Labor Naming Conventions

This project is an AI-driven investment tool. In code related to DCA, historical scanning, and AI analysis, strictly follow the division principle of "Rules calculate facts, AI provides explanations", and reinforce this boundary through naming.

Rule Layer Data Models

The rule layer only outputs recalculable structured facts; subjective conclusions are strictly prohibited.

Suffix	Definition	Intra-module Example	Cross-module Example
`*Facts`	Structured fact snapshot (date, amount, interval, etc.)	`Facts`	`DcaFacts`
`*Check`	Rule validation result (hit + deviation + explanation)	`Check`	`DayCheck`
`*Flag`	Exception marker (no conclusion, only marking)	`Flag`	`Flag`
`*Draft`	Proposed solution (not stored, in-memory structure)	`Draft`	`PlanDraft`
`*Result`	Internal intermediate aggregation (e.g., backfill result)	`Result`	`BackfillResult`
`*Report`	Report for CLI/AI display	`Report`	`ScanReport`

Simplification Principle: Omit the prefix when the module path already contains domain information; retain context when exporting across modules.

Flow Function Verbs

Verb	Constraint	Intra-module Example	Cross-module Example
`build_*()`	Read-only calculation, returns `*Facts`	`build_facts()`	`build_dca_facts()` (batch as parameter)
`scan_*()`	Read-only, side-effect-free (idempotent)	`scan()`	`scan_trading_history()`
`draft_*()`	Returns `*Draft` , not stored	`draft()`	`draft_dca_plan()`
`backfill_*()`	Write operation, modifies database	`backfill()`	`backfill_dca()` (no need for for_batch)

Key Principles:

Seeing
```
scan_
```
/
```
build_
```
/
```
draft_
```
means it is safe to call (read-only)
Seeing
```
backfill_
```
means to be cautious as it modifies the database
Use parameters rather than function names to express "what" (e.g., batch_id, fund_code are parameters)

AI Layer (Reserved)

AI generates semantic explanations based on

*Facts

from the rule layer, only writes explanatory fields, and does not modify core data.

```
*Insight
```
: Insights (e.g., "This transaction may be limited by quota")
```
*Explanation
```
: Natural language explanation
```
*Label
```
: Classification label

Pre-submission Checks

Whenever possible:

Run static checks (e.g.,
```
ruff check --fix .
```
as configured in the project).
Quickly review the current diff to confirm:
- Style cleanup does not change business behavior
- No debugging code is left behind (e.g.,
```
print
```
  ,
```
breakpoint()
```
  ).

code-style

NPX Install

Tags

SKILL.md Content (Chinese)