Python style
- Type hints throughout. Functions and variables are annotated; modern code uses
from __future__ import annotationsso annotations stay evaluatable without runtime cost. A function's signature should tell you what it accepts and returns without reading the body. - Ruff for linting, mypy for type-checking. Both run in CI as a gate, not a suggestion -- a change that fails either doesn't merge. This portfolio's own backend is built exactly this way: every module here passes
ruff checkandmypybefore anything else runs. - Comments explain why, not what. Well-named functions and variables already say what the code does; a comment earns its place only when it captures a non-obvious constraint, a tradeoff, or the reason something is written an unusual way.
- Tests for behavior, not for coverage numbers. A test should demonstrate a specific claim -- "this rejects an unsupported claim," "this degrades instead of crashing" -- not just execute a line.
Repository structure
Each project gets its own repository rather than living inside a monorepo of unrelated work -- a reviewer (or a hiring manager) can clone exactly one thing and run its tests without pulling in context they don't need. The public reference projects on this site follow that pattern: acceptance-harness, airgap-messaging-ingest, shoplabs-lakehouse-lab, and careerassistai-scoring-pipeline are each self-contained, with their own README, tests, and CI config.
AI coding tools
Four frontier AI tools are part of the day-to-day workflow, used for different jobs rather than interchangeably:
- Claude (Claude Code) -- the primary agentic coding tool used to execute large implementation passes under explicit architecture, evidence, safety, and review constraints.
- In-editor coding assistant - used for faster in-context work: targeted edits, refactors, and code review while staying inside the IDE rather than switching to a terminal-driven session.
- Grok - used for fast iteration and second opinions: sanity-checking an approach, exploring alternatives, or getting a quick answer without spinning up a full agentic session.
- Codex - used for focused code generation and review, particularly where a narrower, single-file change is the right scope for the task.
The point isn't "which tool is best" -- it's picking the right tool for the size and shape of the task, and always verifying the result with tests and type/lint checks rather than trusting output blindly.
Same discipline, AI-assisted or not
The same rules apply whether a line of code came from a human or a model: it needs a type signature, it needs to pass lint and type checks, and it needs a test that demonstrates the behavior it claims to have. See Hiring Manager Proof for how that discipline shows up in this site's own architecture.