post-kit: Instructions file for Kiro

Python & FastAPI — Code Standards

Write code like Netflix Dispatch, Starlette, and encode/httpx: clean, obvious, boring in the best way.

Single Responsibility

Every function does ONE thing. Every file has ONE purpose. Every class has ONE reason to change.

• A function that fetches data does not also format it.
• A function that validates does not also save.
• A file with routes does not contain business logic.
• A file with business logic does not import FastAPI.

The test: Can you describe what this function/file does in one sentence without using "and"? If not, split it.

Function length: If a function exceeds 20-25 lines, it's probably doing two things. Extract the second thing.

File length: If a file exceeds 200 lines, it has too many responsibilities. Split by concern.

How Top-Tier Repos Write Python

Naming tells you everything

# Bad — what does this do?
def process(data):
    ...

# Good — name IS the documentation
def parse_front_matter_from_markdown(content: str) -> dict[str, str]:
    ...

• Functions: verb + noun (get_posts, parse_config, emit_event, rebuild_index)
• Variables: descriptive nouns (post_content, active_modules, niche_config)
• Booleans: is_ / has_ / can_ prefix (is_onboarded, has_analytics, can_scout)
• Constants: UPPER_SNAKE (MAX_RETRY_COUNT, DEFAULT_PORT)
• Private: _underscore_prefix (internal, don't call from outside)

Small, focused modules

# How Netflix Dispatch structures a domain:
module/
├── router.py       # HTTP in/out only — thin
├── service.py      # All logic — thick
├── models.py       # Data shapes — Pydantic schemas

Router is thin (10-50 lines per endpoint). Service is where the work happens. Models define the contract.

Type everything

# Every function signature is fully typed
async def get_posts_by_status(
    status: PostStatus,
    limit: int = 50,
    offset: int = 0,
) -> list[PostSummary]:
    ...

No Any. No untyped parameters. No untyped returns. The types ARE the documentation.