Writing a Teaching Specification
A companion to the Teaching Matters column “Teaching Your AI How You Teach.”
A specification is a standing document that states how you build course material, written in enough detail that an AI model can follow it. You write a first version in an afternoon, keep it in a project workspace, and correct it as you use it. This guide assumes no prior experience with these tools.
This page was drafted with Claude and revised by me before posting.
The web version at subhadipchowdhury.github.io/pedagogy/specification/how-to-guide/ is the copy I keep current, and there each prompt is a copy-to-clipboard block. This PDF is a snapshot of September 3, 2026 and won’t be updated. Licensed CC BY-NC-SA 4.0.
Step 1
Narrow the scope
Pick one course and one kind of material: worksheets, problem sets, exam questions, lab handouts, discussion prompts, reading guides. You can’t write down “how I teach” in an afternoon. You can write down “how I write weekly discussion worksheets for Introductory Calculus.” Add the other kinds later, as new sections.
Step 2
Create the project and put your examples in it
A project is a workspace that loads the same files and instructions into every conversation you start inside it, so you stop re-explaining yourself. Make it before you write anything else.
- Click
Projectsin the left sidebar, create a new one, and name it after the course. - Collect a dozen or so pieces of that material you’ve already made and would hand out again. Hold two or three of them back and keep them out of the project, because you’ll need work the model hasn’t seen when you test the specification in Step 7. The eight to ten that remain are what it learns from.
- Pick those eight to ten for range: different weeks, different topics, the short ones alongside the long ones. A rule is whatever holds steady across pieces that otherwise have little in common, so ten varied pieces teach the model more than thirty near-copies. If your material is already compiled, a single file covering a whole year counts as one upload and reads fine.
- Add two or three pieces you were unhappy with, and put the word
rejectin each filename, since the prompt in the next step refers to them that way. Upload these as separate files even if the rest of your material is one compiled file. They carry more per file than the successes do, because you can usually name what went wrong in a piece you shelved. - Upload everything to
Project knowledge. Scans and photographs are usable, though the model reads a text or Word file more reliably than an image of one.
Leave Project instructions empty for now. You’ll write them in Step 5, once the specification exists.
Does it have to be a Projects workspace?
Two other workspaces do the same job, and both put the specification on your own computer where Claude edits it in place, rather than you downloading it, editing it, and uploading the new copy every time a rule changes.
- Cowork mounts folders from your computer into a project, and the scheduled review of Step 9 then runs inside that project. Cowork projects are desktop-only, aren’t synced, and can’t be shared with a colleague.
- Claude Code runs as a panel inside the VS Code editor and works directly in a folder of course material. The project instructions of Step 5 become a file called
CLAUDE.mdin that folder, and under version control you get a dated history of every rule you added and what prompted it. It’s a programmer’s tool, so expect unfamiliar surroundings if you don’t already work in an editor.
The steps below stay on the Projects route, which runs in a browser apart from the optional review in Step 9. Nothing here locks you in, since the specification is the same file whichever workspace you keep it in.
Step 3
Ask for the first draft
Start a conversation inside the project and ask for something like this.
Read the materials in this project. I want a specification document detailed enough that you could write a new piece in my style by following it. Infer the design rules I appear to be using, covering structure, sequencing, difficulty, voice, how much I explain versus how much I ask, and anything I consistently avoid. The files marked as rejects are ones I was unhappy with; say what distinguishes them from the rest. Write the result as a numbered list of rules. For each rule, name the file you drew it from, and mark anything you are guessing at.
Expect a draft that is more right than wrong and nowhere near finished. Correcting a stated rule takes far less time than composing one from a blank page.
Step 4
Fix the draft
Make three passes over what came back. This is the step that takes the afternoon.
The first pass checks the inferred rules against the material. A model reading ten pieces generalizes from accidents, so it might report that you always open with a figure when seven of them happen to, or promote a constraint from one unit, the term you taught in a room with no projector, into a standing rule. Read each rule and ask whether your material actually follows it. Delete what is wrong about you and correct what is half right.
The second pass sharpens whatever is still vague. Keep a rule only if a colleague, reading a draft, could tell you whether it had been followed.
The third pass adds what no amount of reading would reveal. The rejects show a few failures you kept a copy of. They can’t show the draft you abandoned halfway, the topic you refuse to assign, or the framing you’ve never once used. Ask yourself what makes you throw material away, and write those answers down.
Then stop, while the specification is still thin. Most of the rules in mine arrived later, from cases I hadn’t met yet, and you write yours in Step 8.
What the specification becomes
Over a term or two, mine has settled into six sections. Don’t try to write them all today.
- Purpose and audience. What the material is for, who the students are, what they have already seen, how they will be assessed.
- Design principles with their reasons. Why prediction comes before computation, why a derivation or a proof becomes an exercise with blanks, why an applied context sometimes gets in the way. A model can extend a rule to a case you didn’t anticipate only if it knows why the rule is there.
- Rejection triggers, from the third pass of Step 4. Models default to the safe, textbook-shaped version of everything, so the prohibitions do more work here than the instructions do.
- Voice and prose. Banned words and constructions, register, how you address students, formatting habits.
- Format conventions. Section structure, numbering, length limits, the ratio of exposition to student work, and any typesetting or template details.
- One annotated example. A single piece of material you consider correct, with notes on what each part is doing and why it sits there. This can be one of the pieces you held back in Step 2, once you’ve finished testing with it.
Step 5
Add the specification and write the instructions
Save the corrected document as a file, named for the course: calculus_specification.md, or whatever the equivalent is for yours. Upload it to Project knowledge next to the examples, along with anything else the model should have on hand: syllabus, learning goals, the table of contents of the textbook, last year’s exams.
Now write the Project instructions. Four or five lines is enough.
This project produces material for [course]. Treat [course]_specification.md as the authoritative reference and consult it before drafting anything. Where these instructions and the specification disagree, the specification wins. Mark anything you are unsure of, including computations, claims, and references, and do not paper over a gap in a derivation. Propose the structure of a new piece and wait for my approval before writing it out in full.
Keep the instructions short and let them point at the specification. You can revise a file properly, keep the old copies, and hand one to a colleague. A text box gives you none of that. Come back to the instructions periodically, per Step 10.
Step 6 · optional
Write a second, shorter document
Keep this one separate from the specification: it covers how the model talks to you while you’re working, not what it produces. By default it will spend your reading time on validation, summary, and hedging.
A skill is a named markdown file of instructions that Claude loads when the work calls for it. Mine is called no-fluff-response, and you can download the packaged copy. It requires the first sentence to be the answer or the correction, and it bans openings that praise the question, closing offers of further help, and narration of what the model is about to do.
Write your own version and add it as a skill. Because a skill loads only when the work appears to call for it, add a line in Settings > Profile asking Claude to apply this one in every conversation.
Step 7
Test before you trust it
Ask the project to produce one of the pieces you held back in Step 2, then compare its version against yours. Wherever the output diverges from what you would have written, work out which of three things happened: the specification says nothing about that point, says the wrong thing, or is right and the model went straight past it. The first two you fix by editing. For the third, restate the rule as a prohibition, which a model follows more reliably than a preference. Two or three of these tests found most of what was missing in mine.
The test checks style. Nothing in it, or in the specification, checks whether the content is correct. A model states a wrong claim as fluently as a right one, so read everything for accuracy before it reaches students. The line in the project instructions asking it to mark what it is unsure of helps a little, but only a little: it shows you where the model noticed a gap, and the errors that matter are the ones it made confidently. You check the content accuracy and the logic yourself.
Step 8
Correct in use
Each time you get a draft back:
- Find where it falls short.
- State the principle behind the shortfall rather than fixing the instance, and keep a running list of these. Say “no question may name the theorem it is testing” rather than “cut the phrase mean value theorem from the hint in question 3.”
- Once the same infraction has appeared three or so times, promote the principle from that list into the specification as a numbered rule.
Correcting the model in conversation doesn’t change the uploaded file, so promote a rule by editing the specification and replacing the copy in Project knowledge. If the model keeps obeying the letter of a rule while missing its point, the rule is describing a symptom. Rewrite it one level up, so that it names the principle underneath.
Step 9 · optional
Put the review on a schedule
Correcting as you go catches only what you happen to notice, so I run a scheduled pass as well. Claude Cowork runs a saved prompt on a schedule and can read your earlier conversations. The task writes a memo of proposals and never touches the specification, so promoting a rule is still an edit you make yourself. Mine runs every two weeks, on the following standing instructions.
- Read the conversations from the last fourteen days that concern the course material, and ignore the rest.
- Keep only the durable items, meaning new or changed conventions, design decisions, prose constraints, and corrections I made to earlier guidance.
- Check each of those against the current specification and discard anything it already covers.
- Write a dated memo giving, for each surviving proposal, the target section, a one-line rationale, the conversation it came from, and old text and new text I can paste in directly.
- Treat the specification as read-only, and when there is nothing worth adding, say so in one line rather than inventing something.
Step 10
Reorganize as it grows
Past twenty pages or so, split the specification into three layers so you can revise one without disturbing the others.
- Core. Principles that hold across everything you teach.
- Context. The course and the term, which you swap out each time you teach it.
- Conventions. One section for each kind of material, worksheets, exams, solution keys.
The six sections map onto the layers. Purpose and audience becomes Context. Design principles, rejection triggers, and voice become Core. Format conventions and the annotated example become Conventions.
Once a term, do a structural pass yourself. Replace Context for the new quarter, condense the sections for kinds of material you aren’t currently using instead of deleting them, and reconcile any rules that have changed so that two versions of the same rule don’t both sit in the specification. This is also where you write down a design that didn’t work in class, since the specification will keep producing it until you say otherwise.
Review the project instructions in the same sitting, since they name the current course and the drafting workflow and go stale faster than the specification does. Ask the model to propose a revised set, read the proposal line by line before accepting any of it, and look in particular for instructions that have grown into a competing copy of the specification or that still describe a course you no longer teach.
Where to get help
- Claude Projects, which is the workspace described in Step 2, at https://support.claude.com/en/articles/9517075-what-are-projects
- Skills, which are used in Step 6, at https://support.claude.com/en/articles/12512176-what-are-skills
- Projects in
Cowork, the alternative noted in Step 2, at https://support.claude.com/en/articles/14116274-organize-your-tasks-with-projects-in-claude-cowork Claude Codein VS Code, the other alternative noted in Step 2, at https://code.claude.com/docs/en/vs-code- Scheduled tasks in
Cowork, which are used in Step 9, at https://support.claude.com/en/articles/13854387-schedule-recurring-tasks-in-claude-cowork - Claude training sessions and materials for UChicago accounts, at https://intranet.uchicago.edu/tools-and-resources/tools-and-applications/claude
- The CCTL’s AI resources page and its one-on-one consultations for instructors, at https://teaching.uchicago.edu/resources/programming-and-resources-ai