claude.md

Project context for Claude Code

3 min read source

Project context for Claude Code

Personal interview-preparation knowledge base — markdown notes on interview questions, gotchas, and patterns. ~1,000 files across 8 top-level domains.

Target: 2026-2027 interviews. Primary focus is backend Python + AI/ML (classical ML through LLM/RAG/agentic/MCP). Frontend and DevOps/platform are also in scope — secondary priority, but maintained to the same standard, not de-scoped.

The three control documents

Read these before working. They are the source of truth, in this order:

  1. STACK_BASELINE.md — verified current versions and facts. Every claim you write about a version, release, or deprecation is checked against this. If a row is older than ~3 months, re-verify it with a web search and update the file in the same commit.
  2. PLAN.md — the phased modernization plan and its progress table. Work one phase per session.
  3. LEDGER.md — per-file review tracker. Update it in the same commit as the content change.

Repo conventions

  • No build step. Pure markdown. No pyproject.toml, no test runner, no linter — don’t search for one.
  • File naming: NN_topic.md, zero-padded. Numbers reflect reading order, not creation order. Contiguous within a folder — a gap is a real gap.
  • Top-level folder numbering is stable; append when adding a section.
  • Cross-folder overlap is fine when topics legitimately live in two places. Write in the more specific folder and cross-link the broader one.
  • The git repo is py-prep/, nested inside a non-repo tech-interview-prep/ parent.

Style — one style, no exceptions

Templates: any file in backend/02_python_core/tricky_questions/ or typing/.

  • Headline: # Title only. No emoji, no metadata block.
  • No emoji anywhere — not in headers, not in body. (~74 legacy files still violate this; they get rewritten, not extended.)
  • No **Answer:** Q&A blocks. Write prose and code, not a quiz transcript. (~87 legacy files still violate this.)
  • Length: ~80–250 lines. Scannable in 3 minutes.
  • Voice: direct. “Use X. Don’t use Y because Z.” Not “You might want to consider…”.
  • Code blocks: always tag the language — ```python, never bare ```. Minimal repros, 5–15 lines. Show the effect, not the setup.
  • Tables for comparisons (X vs Y) — denser than bullet lists.
  • Cross-link with relative markdown links — same folder [NN_topic.md](NN_topic.md), up a level [../folder/NN_topic.md](../folder/NN_topic.md). Count the ../ carefully; the link checker catches wrong depth.
  • End with ## Interview angle — 2–4 questions an interviewer would actually ask, with the gotcha follow-up where there is one.

Currency rules

These exist because the repo drifted badly: it had Python 3.11 as the baseline when 3.14 shipped, GPT-4 as the model example, and Kafka 2.4 after ZooKeeper was removed in 4.0.

  1. Check STACK_BASELINE.md before asserting any version, date, or deprecation. If it’s not in the table, web-search it and add the row.
  2. Date claims that will rot: “As of 2026-08, …”.
  3. Prefer capability-neutral phrasing where the specific product doesn’t matter — “a frontier model” ages better than a model name in a sentence about prompt design.
  4. Watch for guidance changes, not just version bumps. The React Compiler didn’t only change a version number — it made most useMemo/useCallback advice wrong. Free-threading becoming official in Python 3.14 rewrites the GIL story. When a version changes the advice, rewrite the note, don’t patch the number.
  5. Never leave a bare unversioned claim that was only true in 2023.

Content rules

  • Delete freely. A 1-line stub is worse than no file — it implies coverage that isn’t there. Prune rather than pad.
  • Read before you write. Every file in a phase’s scope gets opened, not just the ones that look wrong.
  • Don’t create a file you can’t fill. No placeholder READMEs.

Workflow

  1. One PLAN.md phase per session. Bundling causes sprawl — this repo has that scar already.
  2. Write independent files in parallel (batch Write calls in one message).
  3. Commit per logical group. Short imperative subject, no Conventional-Commits prefix, Co-Authored-By trailer.
  4. Update PLAN.md’s progress table and LEDGER.md in the same commit as the content.
  5. Work on the modernize-2026 branch. Don’t git push unless asked.

How to find things

  • Topic search: rg -l "<term>" --type md
  • By filename: Glob with **/<keyword>*.md
  • Index: README.md — check there before assuming a topic doesn’t exist.
  • Real interview signal: techcheck/questions.md is a debrief of actual questions asked. When prioritizing, weight toward what’s in there.