← Tools I Use

What Stanford's CS336 CLAUDE.md Teaches About Steering AI Agents

2026-06-02 · ~6 min read · Conor Dobbs

Stanford's CS336 course shipped a CLAUDE.md file to its public assignment repo, and it climbed to the front page of Hacker News with 312 points. The interesting part is not the academic-integrity angle everyone latched onto. It is that a graduate-level systems course accidentally published one of the cleanest public examples of how to steer a coding agent.

Most developers I talk to treat CLAUDE.md as a README with a different name. They paste in a project description, maybe a list of npm scripts, and call it done. Stanford treated the file as a behavioral contract. That difference is the whole lesson, and it transfers directly to the way you and I use these tools at work.

What the file says

The course is CS336, "Language Modeling from Scratch," where students implement tokenizers, transformer blocks, optimizers, and training loops by hand. The whole point is to learn by building. An AI agent that writes the optimizer for them defeats the exercise. So the CLAUDE.md does not ban the agent. It re-roles it.

The file defines the agent as a teaching aid, not a solution provider. Then it splits its instructions into two explicit lists.

The required actions: explain concepts, reference the lecture handouts and official PyTorch and Triton docs, review student code and suggest edge cases, debug by asking questions instead of handing over a fix, clarify Python and CUDA error messages, and propose sanity checks like toy examples and assertions.

The prohibited actions are blunter, and they are quoted directly in the file: do not "write any python or pseudocode," do not "give solutions to any problems," do not complete the TODO sections, do not edit the student's repository, do not run bash commands, and do not implement the core components, namely "tokenizers, transformer blocks, optimizers, training loops, Triton kernels." It also forbids pointing students at third-party implementations on GitHub.

That is it. A role, a list of things to do, a list of things never to do, and a one-line statement of intent at the bottom: "The goal is for students to learn by doing, not by watching an AI generate solutions."

Why this is good prompt engineering, not only a school rule

Strip away the classroom context and you are left with a template that works for any project. The structure is doing three things that most CLAUDE.md files I see do not.

First, it assigns a role before it assigns tasks. "You are a teaching aid" changes every downstream decision the model makes. Role framing is the cheapest, highest-impact instruction you can give an agent, and almost nobody uses it. Your project file probably tells the model what your app does. It probably does not tell the model who it is supposed to be while working on it.

Second, it uses a hard forbid list with concrete nouns. "Do not refactor" is vague. "Do not implement tokenizers, transformer blocks, optimizers, training loops, Triton kernels" is enforceable, because the model can pattern-match against those exact things. When I write rules for my own agents, the ones that hold up are always the specific ones. "Never edit files in migrations/" beats "be careful with the database" every time.

Third, it separates capability from permission. The agent is fully capable of running bash and writing Python. The file removes the permission anyway. That is a real pattern for production work, where the model could do something destructive and you do not want it to, regardless of whether it can.

The honest limitations

I am not going to pretend this solves the problem the course wanted to solve. The top HN comment said it plainly: there will always be a model outside the curriculum that a student can use to bypass the guidelines. A CLAUDE.md only governs the agent that reads it. Paste your assignment into a chat window with no project file and none of these rules apply. The guidelines are a speed bump, not a fence.

Another commenter pointed out the file looks close to an agent.md that circulated a few months earlier, and to Stanford's credit they did cite the original. That is worth sitting with too. Good agent instructions are converging on a shared shape, the same way good README conventions did a decade ago. We are watching a format standardize in real time.

And the deeper objection in the thread is the one I find most honest: maybe the answer is not to restrict the tools but to raise the bar. If professionals are going to use agents, scale the difficulty of the assignment to assume that. Restricting the agent teaches the fundamentals. Raising the difficulty teaches the fundamentals plus the tool. Reasonable people in that thread disagreed, and I do not think either side is plainly wrong.

What to take back to your own repo

Forget the school for a second. Open the CLAUDE.md in whatever you are building and ask three questions.

Does it give the agent a role, or only a description? Does it have a forbid list with specific file paths, commands, and module names, or only vibes? Does it separate what the agent can do from what it is allowed to do?

If the answer to any of those is no, you have a free upgrade sitting in front of you. A behavioral contract costs ten minutes to write and pays itself back the first time the agent does not blow away your migrations folder or "helpfully" rewrite the file you told it to leave alone. Stanford wrote one to keep students honest. The same structure keeps your agent inside the lines on a real codebase, which is a problem a lot more people have than they admit.

The funny thing about the whole CS336 episode is that the most useful artifact the course produced this week was not a lecture on attention. It was a config file. If you collect these patterns the way I do, there is a running set of CLAUDE.md setups and hook recipes over at tools.thesoundmethod.me. Worth reading the next time you open yours.

Sources

Related reading