# Code Style

> Apply railtracks' code-style conventions whenever writing or editing Python code in this repo: new functions, modified signatures, docstrings, comments, imports, error handling. Use this automatically as part of any code change, not just when explicitly asked to clean up code.

- Skill: `railtownai/code-style` (Agent Skill)
- Install (CLI): `npx skillmds@latest add railtownai/code-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/railtownai/code-style/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: RailtownAI (https://skillmd.com/u/railtownai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/railtownai/code-style

---


# Code style

Before finishing any code change in this repo, check the diff against these rules. Each one comes from a
recurring, repeated PR review comment on railtracks, not a hypothetical style preference.

- **Lint/format**: run `ruff check --fix` and `ruff format`, required for every PR (CI-enforced), so treat
  a change as unfinished until both are clean.
- **Imports**: prefer top-level imports. Local/inline imports are fine when there's a real reason (e.g.
  deferring an expensive or optional dependency like `litellm`); don't add them out of habit, and don't
  let a lint failure be the excuse either way.
- **Tests**: new functionality gets tests in the matching package's `tests/` directory; don't leave a
  behavior change uncovered.
- **Docstrings**: must match the actual signature (param names, types, `| None` / `Iterable[...]` etc.).
  Update the docstring any time a signature changes.
- **Tool docstrings/type hints**: for any `@rt.function_node`-wrapped tool, the docstring is the literal
  tool description the LLM sees and the type hints define its JSON schema parameters; don't write vague
  docstrings or omit type hints on a tool function.
- **Module-level comment strings**: a docstring at the top of a file is welcome. Avoid long inline
  paragraph-style comments in the body of the code; keep inline comments short and targeted.
- **Typing**: no bare `Any` when a concrete type is available or already imported nearby. Don't reach for
  `Any` as a quick fix to silence something that's actually broken, either; fix the real type mismatch.
- **TODOs**: no inline `# TODO` comments. Either fix it now or file a tracked GitHub issue and reference it.
- **Cruft**: no dead/commented-out code, no stray debug/scratch files left in a change.
- **Mutable defaults**: don't store a mutable default (`x or []`) by reference and mutate it later; copy
  defensively.
- **Errors**: use `repr(e)` rather than `str(e)` in error/log messages.
- **`__init__.py`**: don't add docstrings to `__init__.py` files; not this repo's convention.
- **Consistency with siblings**: when adding a new variant of something that already has 2+ siblings
  (chunkers, loaders, LLM providers, etc.), match their existing shape/behavior rather than introducing an
  ad hoc one-off.