Course Notes | Stanford CS146S: The Modern Software Developer, Lecture 1. Course site: https://themodernsoftware.dev/
I use Claude Code every day, but I could not explain how a sentence turns into a series of file edits. How does the model know which tool to call? Where do the definitions of 40 tools actually live? And when the context fills up, how does it compress the earlier conversation?
The first week of Stanford CS146S answers these questions with three things: a 200-line minimal agent, an intercepted Claude Code request, and a 55-page paper.
1. The course
CS146S is The Modern Software Developer. Stanford offers it in Fall 2026, 3 units, Tuesday and Thursday, 5:30 to 6:20 p.m. The instructor is Mihail Eric; the teaching assistants are Isaac Kan, Vijay Daita, and Patrick Hua.
The course page is direct about its premise: large language models have turned software development from a mostly manual coding process into collaboration with increasingly capable coding agents. The course teaches three things: how to give an agent the right context, how to translate product requirements into executable specifications, and how to design a loop in which humans and agents plan, build, evaluate, and improve software together.
The 10-week schedule:
| Week | Topic |
|---|---|
| 1 | Inside a coding agent |
| 2 | Context engineering |
| 3 | Agent skills and the CLI |
| 4 | Customizing the agent and the repository |
| 5 | Making repositories agent-ready |
| 6 | Agentic code review |
| 7 | Security |
| 8 | Background agents |
| 9 | Building an AI-native team |
| 10 | The software factory and the future |
The guest list is not filler: Boris Cherny, the creator of Claude Code; Amjad Masad, CEO of Replit; Silas Alberti of Cognition; Isaac Evans of Semgrep; Rajesh Bhatia of Cloudflare; Lee Robinson of SpaceX; Eno Reyes of Factory; and investor Elad Gil.
Grading: final project 50%, open-source contributions 30%, weekly assignments 15%, class participation 5%. Open-source work is 30% of the grade, a heavier weight than most courses give to a project.
Prerequisites: programming experience at the CS111 or CS161 level; CS221 or CS229 is recommended. The FAQ says you do not need prior experience with Claude Code or similar tools, but you do need strong programming fundamentals. Expect 10 to 12 hours a week.
Who is it not for? People who want a few prompt tricks that make AI do the work. The first week alone involves intercepting requests, reading JSON, and counting how much context the tool definitions consume. It is also not for people who have never written code: the assignment asks you to intercept Claude Code requests and parse them yourself.
Who is it for? People who use coding agents every day but cannot explain what happens inside. Or people building agent products who want to know where the production system differs from the demo.
2. What Week 1 covers
Week 1 is called The Internals of Coding Agents. Two classes and one paper answer three questions: how does an agent run, what does a production system add, and why does it add those things?
Tuesday: 200 lines, get the loop running
Mihail used only 3 tools: read a file, list a directory, and edit a file.
The code structure is simple: a tool registry that maps a tool name to an implementation; a system prompt that describes each tool’s name, purpose, and arguments; a while True loop; and a messages list that records what the user said, what the model replied, and what the tool returned.
The loop does four things: send messages to the model; extract tool calls from the reply; execute the tool; append the result to messages.
The model does not run anything. It emits text that says it wants to call edit file with certain arguments. The harness parses that text as JSON, finds the matching function, executes it, and puts the result back. On the next turn, the model sees the result and continues.
That is the skeleton of an agent. The 200 lines prove that the loop is not magic. In half a day, someone who can write Python can get a model to read files, list directories, and edit code.
But they do not prove that the agent can be handed to someone else. Between a demo and a product sit permissions, logs, recovery, and boundary checks. Those do not fit in 200 lines.
Thursday: intercept the request, see the real system
Mihail used a proxy to capture Claude Code’s requests and responses as JSON. The first thing you see is the tool list.
Claude Code ships with about 40 tools: read a file, write a file, run bash, search the web, query LSP, spawn a subagent, enter plan mode, invoke a skill, send a notification, ask the user a question. Each tool has a name, a description, and an argument schema, and all of it is injected into the request.
Is more tools better? Mihail gave a counterexample: an early GitHub MCP server shipped with 110 tools, one action per tool for listing issues, creating issues, and commenting on issues. The more tools you add, the fatter the context, and the easier it is for the model to get lost in irrelevant material.
He also gave a number: Claude Code’s system prompt is now 50 to 80 lines, down from 200 to 250. A month ago, Anthropic cut another 8%. Why? Because users never see that text, but every request pays for it in tokens.
Beyond the system prompt is a layer you control: CLAUDE.md or AGENTS.md. It is injected as a user block that says these instructions override default behavior and must be followed exactly. The project structure, test commands, and startup steps you put there are taken seriously by the model.
Further out are plan mode, skills, subagents, hooks, and compaction. Plan mode is essentially a workflow description. A skill shows only a name and a one-line description until the model decides it is relevant, then the full text is pulled in. A subagent gets a fresh context window, does its work, and returns only the result. Hooks are lifecycle events. Compaction summarizes earlier content when the context is nearly full, taking 500,000 tokens down to 150,000, and the model continues.
All of these mechanisms point to the same constraint: the context window is finite, and tools, prompts, and history all compete for it.
Reading: a 55-page paper
Week 1 includes a 55-page paper: Dive into Claude Code. Its subtitle is The Design Space of Today’s and Future AI Agent Systems.
The paper reads Claude Code’s public TypeScript source and compares it with two open-source agent systems: OpenClaw and Hermes Agent. One sentence in the abstract is almost the answer to Week 1: the core is a simple while loop that calls the model, runs tools, and repeats; most of the code, however, lives around that loop.
What is around it?
A permission system. Seven permission modes plus a machine-learning classifier. In the default mode, anything beyond read-only access needs your approval. acceptEdits auto-approves edits inside the working directory. plan mode produces a plan before execution. bypassPermissions skips most prompts but keeps safety-critical checks.
One number in the paper is hard to ignore: Anthropic found that users approve about 93% of permission prompts. 93%. Click enough times and you stop reading. So Claude Code did not add more warnings. It changed the structure: sandbox what can be sandboxed, classify what can be classified, and make deny rules always outrank allow rules. When an action is denied, the model does not simply stop; it receives the reason and tries a safer approach.
A compaction pipeline. Five layers, from light to heavy: cap the size of each tool result, trim old history, run cache-aware microcompaction, project the context at read time, and finally ask the model to summarize. Why five layers? Because every compression loses information, and the goal is to lose as little as possible.
Four extension mechanisms: MCP, plugins, skills, and hooks. They are ordered by context cost. Hooks cost nothing by default. Skills cost one description line until invoked. Plugins are a packaging layer with medium cost. MCP costs the most once its tool schemas load.
Subagents have their own context windows and permission boundaries. Session storage is append-only: it only appends, never rewrites. When a session is resumed, permission state is not restored. These are deliberate choices.
The paper ends with a longer-term concern: Anthropic surveyed 132 engineers and researchers and found that about 27% of Claude Code tasks were work that would not have been attempted without the tool. But another study found that developers in AI-assisted conditions scored 17% lower on comprehension tests. The paper calls this the paradox of supervision: the more you depend on the tool, the more you need the ability to supervise it, and that ability may be eroding.
3. Structure, utility, and the loop
Structure: three layers, three questions
Week 1 is not three unrelated pieces. It is three layers:
| Layer | Content | Question |
|---|---|---|
| Hands-on | 200-line minimal agent | How does an agent run? |
| Observation | Intercepted Claude Code request | What does a production system add? |
| Theory | 55-page paper | Why those additions? |
The order matters. Build first, and you learn the minimum a loop needs. Intercept next, and you see how much the real system adds around the loop. Read the paper last, and you learn that those additions are design trade-offs, not arbitrary features.
Utility: what each layer solves
The 200 lines remove the mystery. Many people assume a coding agent is a complex intelligent system. Then they see 3 tools, a while loop, and a messages list, and realize how small the skeleton is. A small skeleton is one you dare to modify.
Intercepting the request turns context from an abstraction into countable tokens. You do not have to guess how much space 40 tools take; capture one request and count. You can also see the system prompt, CLAUDE.md, and tool schemas queueing for the same window.
The paper gives you judgment. Seven permission modes are not mandatory for every agent, and five layers of compaction are not the only design. But the paper explains what each mechanism solves and what it costs. You can subtract for your own project instead of copying.
The loop: the course structure is itself an agent loop
Connect the three layers and you get a loop:
- Build a minimal loop.
- Capture a real request.
- Compare the gap and find what your loop lacks.
- Read the paper to see how the production system solves it.
- Return to your loop and revise it.
These five steps mirror the agent loop: act, observe, reflect, act again. Week 1 teaches you about agents by using the shape of an agent.
The key is the last step: returning to your own loop. Watch without building, and the loop is broken. Build without reading the paper, and you reinvent wheels. Read without building, and you get a map, not a road.
Limits: Week 1 is only a map
The 200 lines do not include permissions, recovery, or persistence. The paper is a snapshot of one version of Claude Code, and the system keeps changing. Week 1 covers internal structure, not full engineering practice. Treat the three layers as a starting point, not an endpoint.
4. What I learned by comparing
I put the 200-line demo, the intercepted request, and the paper’s design principles side by side. Four things stood out.
1. The loop is a protocol, not intelligence
The model emits text; the harness turns text into action. You can see the protocol in 200 lines, and you can see its scale in a request with 40 tools. Intelligence lives in the model; engineering lives in the harness.
2. Context is a hard constraint
Tools, the system prompt, CLAUDE.md, and history all compete for the same window. 40 tools are not free, and 110 MCP tools are even less so. Before adding a tool, count the tokens. Before writing CLAUDE.md, ask whether the sentence actually changes execution.
3. Safety and recovery are architecture, not prompts
A 93% approval rate means that asking every time is unreliable. Deny-first rules, sandboxes, classifiers, and retry paths after a denial are structural designs. Not restoring permission state on resume is also a structural choice.
4. The gap between demo and product is the harness
200 lines can complete one task, but they cannot run in someone else’s repository. Permissions, logs, compaction, subagent isolation, and session persistence are the product.
Materials
Original paper: https://arxiv.org/abs/2604.14228
Chinese translation: a 58-page PDF. Quark Drive: https://pan.quark.cn/s/93ee31071271 (access code: 1jLF). The translation keeps the paper’s section structure; formulas and tables are intact.
