I Use Claude Code on an Unfamiliar Codebase

What happened

I now have enough concrete content from the source article. Let me write the article.

The Tech Buffet #24 published by Ahmed Besbes on August 29, 2026, documents a hands-on experiment using Claude Code version 2.1.233 on the open-source fastapi-realworld-example-app repository — code the author did not write himself. The post is issue 24 of The Tech Buffet newsletter, which covers practical machine learning and software engineering with more than 1,000 subscribers, and the piece appeared on Hacker News with 1 point and 0 comments.

This article examines what Besbes did, how Claude Code navigated and modified an unfamiliar FastAPI codebase, why the approach matters for working engineers, who stands to gain from it, and what a practitioner should verify before adopting the same workflow. It is aimed at developers who write or maintain Python backend code and are deciding how much to trust Claude Code on production-grade repositories they did not author.

How it works

Ahmed Besbes, a senior ML engineer and author of The Tech Buffet newsletter, published issue 24 of his Substack on August 29, 2026, titled "How I Use Claude Code on an Unfamiliar Codebase." Instead of asking Claude Code to generate a project from scratch — the kind of demo that shows 30 files appearing in a few minutes — Besbes chose the open-source fastapi-realworld-example-app repository by adr1enbe4udou1n as his test subject. That repository implements the RealWorld API specification using FastAPI, PostgreSQL, SQLAlchemy, Alembic migrations, and a pytest suite.

Running Claude Code version 2.1.233 from inside the cloned repository, Besbes gave it a read-only instruction to explore the repo and explain what the application does. Claude completed that task in 47 seconds, identifying the architecture, the layer responsibilities, and a small bug — without being told which files to open. Besbes then escalated through progressively deeper prompts: explain the architecture, trace a feature end to end, run tests, and finally make a small targeted code change.

Claude Code is a terminal-based agent installed via the one-liner curl -fsSL https://claude.ai/install.sh | bash on macOS, Linux, and WSL. Once running inside a project directory, it has access to the filesystem, can execute shell commands, and can read any file the user allows it to trust. Besbes launched it by typing claude from within the fastapi-realworld-example-app directory, confirmed the folder trust prompt, and began issuing natural-language prompts.

Why it matters

The repository's source code is organized across app/api, app/crud, app/db, app/models, and app/schemas directories. Claude inspected README.md, pyproject.toml, app/main.py, and those subdirectories autonomously — without Besbes specifying a reading order. The model traced how an HTTP request flows from app/main.py through app/api/api.py and the per-resource route files, through app/api/deps.py for JWT authentication, into CRUD functions backed by SQLAlchemy, and finally to a PostgreSQL database managed with Alembic migrations. A Claude Pro or Max subscription is required to use the tool.

The practical value Besbes demonstrates is not code generation but code comprehension. Engineers who join an existing team, inherit a codebase from a contractor, or pick up an open-source dependency they need to patch routinely spend hours — sometimes days — building the mental model that Claude assembled in 47 seconds. The fastapi-realworld-example-app is a realistic stand-in for that situation: it contains CRUD operations, authentication, routing, pagination, database models, Pydantic schemas, and a pytest suite, all written by someone else.

Who is affected

The experiment also shows a safety-conscious usage pattern. Besbes explicitly instructed Claude not to modify files during exploration and architecture phases, then asked it to make only a small change once he understood the codebase himself. That sequencing — read, understand, verify, then act — is a concrete workflow for teams that want AI assistance without surrendering oversight. Claude identified a bug during the read-only phase without being prompted to look for one, which hints at a useful side effect of deep codebase traversal.

The primary audience is Python backend engineers and ML practitioners who regularly encounter codebases they did not write: new hires onboarding to an existing FastAPI or Django service, contractors handed a legacy application, open-source contributors trying to understand a maintainer's architecture before submitting a pull request, and technical leads doing due diligence on acquired code. The Tech Buffet newsletter, which has over 1,000 subscribers, is aimed squarely at that constituency.

Secondary audiences include engineering managers deciding whether Claude Code belongs in a team's standard toolchain, and developers who currently hold a Claude Pro or Max subscription but have only used the tool for greenfield generation tasks. Because the fastapi-realworld-example-app is public on GitHub under the username adr1enbe4udou1n, anyone can reproduce Besbes's exact experiment with the same repository and version 2.1.233 of Claude Code, which makes the article directly actionable for teams that want to evaluate the tool before committing to it on internal code.

What to watch next

A builder replicating this workflow should verify two things before trusting Claude's architectural summary on their own codebase: whether Claude correctly mapped the authentication dependency chain — Besbes's prompt confirmed app/api/deps.py handles JWT, but a real service may use multiple auth strategies — and whether the small code change Claude eventually made passes the existing pytest suite without modification. Both checks are possible to run immediately and do not require additional tooling beyond what the fastapi-realworld-example-app already ships.

Besbes explicitly set aside MCP servers, subagents, and Claude's Skills system, noting those as natural next steps once a developer is comfortable running a single Claude instance against a single codebase. For teams already using Claude Code, the follow-on question is whether the same exploration workflow holds for repositories that span multiple services, use non-standard directory layouts, or mix Python with other languages. The Tech Buffet newsletter has over 1,000 subscribers, and Besbes's stated intent is to publish subsequent issues that address exactly those more complex configurations.