Five moves your instructor makes on a real production codebase, scaled down to a personal website.
你的老师在真实生产代码上用的五步,缩小到一个个人网站。
Be clear about what this is. The control loop is the same one professionals use — interview, choose, approve, challenge, verify. The harness around it is not: the real project also runs tests before code, three separate reviewers, and a pipeline that can block a release. Exactly what's left out is at the bottom of this page. You're learning the moves, not the machinery.
先说清楚这是什么。控制回路和专业人士用的是同一套,问、选、批、疑、验。围着它的那套装置不是:
None of these are bugs. Design around them.
这几条都不是毛病。绕着它们设计。
The three facts above are about how the thing is made. These four are about how it behaves once you have handed it work, which is the more useful subject, because a habit, unlike an architecture, is something you can watch it commit.
上面三条讲的是它怎么造出来的。下面四条讲的是你把活交给它之后它是什么德行。后者其实更用得上:构造你看不见,习性是能当场抓住的。
Told to stop, it will report that it has stopped, and go on running; told to finish, it will report the work finished and hand you nothing. A student in the last cohort sat through an evening of this, the tool insisting it had halted while it quietly went on regenerating a video he had already rejected. Of the four this is the expensive one, because nothing in the report distinguishes a false “done” from a true one, and you will not know which you were given until you go and look.
你叫它停,它回你一句停了,然后接着跑;你叫它做完,它回你一句做完了,手里却什么也没有。上一期有位同学整晚都在这上头,工具口口声声说自己停了,其实一直在那儿重做一段他早就否掉的视频。四个毛病里这一个最贵,因为报告里那句“做完了”,真的假的写出来是同一句话,你不亲自去看就分不出来。
Left to itself it will work through the night and have nothing to show for it in the morning. Given seven or eight instructions in one paragraph it will carry out one or two, and it will not tell you which of the rest it dropped. The silence is the part to plan around: it does not refuse the work it has not done, it simply does not raise the subject.
没人盯着,它能做一整夜,早上什么也交不出来。一段话里给它七八条要求,它做一两条,剩下的是哪几条它不会说。要防的是那份沉默:没做的事它不会拒绝,它只是不提。
The meter does not know whether the night produced anything, and it runs the same either way. The wasted hours reach you on the same statement as the useful ones, in the same units, with nothing to mark the difference. That accounting is left to you, and if you do not do it nobody does.
计费那头不管这一夜有没有产出,照收。白费的钟点和有用的钟点上同一张账单,同样的单位,中间没有任何记号。这笔账留给你自己分,你不分就没人分。
Tell it plainly that the horse in the shot is walking backwards, and it will agree that the horse is walking backwards, and run again, and return the same horse. Agreeing costs it nothing, so it agrees readily and often; what it has agreed to is a separate question, and one you can settle only by looking at the next version yourself.
你明明白白告诉它,画面里那匹马是倒着走的,它同意你,说那匹马是倒着走的,重跑一遍,交回来还是那匹马。答应你不花它什么力气,所以它答应得又快又勤;至于它答应下来的到底是什么,那是另一回事,只有你自己看下一版才知道。
None of this is a complaint, and the four are not here to be resented. They are here because the method on this page was assembled against them, one move at a time, by people who had already been caught. You ask for evidence because a report of success is not evidence. You break the work into small tasks because a long instruction loses most of itself on the way in. You stop a run that has stopped producing, since it will not stop on your behalf. And you look at the result yourself, having learned what its agreement is worth.
这些不是抱怨,那四条也不是拿来生气的。它们摆在这儿,是因为这页上的方法本来就是照着它们一条一条搭起来的,搭的人都先被坑过。你要证据,是因为一句“成了”不算证据。你把活拆成小任务,是因为一条长指令进去的路上自己就掉了大半。它不出活的时候你把它掐掉,因为它不会替你掐。最后结果你自己看一眼,它那句答应值多少,你已经知道了。
People get this backwards. The design and the plan are real and they matter enormously — they're what keeps the agent honest between sessions. But you never type them. You talk. It writes them down. You read what it wrote and say yes, no, or “not that part.”
这件事很多人搞反了。设计和计划是真东西,也非常要紧——隔了一个星期还能管住 agent 的就是它们。但那些字不用你敲。你说,它记;你读一遍它写的,然后回答:行、不行、或者“这段不行”。
Say what you want. Pick between the options it offers. Say yes before code exists. Look at the result yourself.
说你要什么。在它给的几个方案里挑。代码还没出来之前先点头。结果自己看一遍。
If you're typing out tasks, stop — that's its job. Yours is harder: deciding, and refusing.
你要是在动手打任务清单,停。那是它的活。你的活更难:决定,和拒绝。
Say what you want. Just don't let it start building. Ask it to interview you first.
你想要什么,说出来。只是别让它上来就写,先让它问你。
I want to build a personal website for myself. Don't write any code yet.
Interview me — one question at a time — until you understand who it's for
and what it needs to do. Then propose 2 or 3 different approaches with the
trade-offs of each, and tell me which you'd pick and why.
Answer the questions. It asks things you hadn't considered — that's the value, not a delay. When it offers approaches, pick one and say why. Then:
把问题答完。它会问到你没想过的地方。那正是它值钱的地方,不是在拖时间。等它给出几个方案,挑一个,说清楚为什么。然后:
Good. Write that up as a design document called design.md: the problem,
the approach we picked, what's in scope, and what we are deliberately NOT
building. Then stop and let me read it.
Read it. Actually read it. Then:
读一遍。是真读。然后:
Approved. Don't start building yet.
Why “what we are NOT building” earns its place: it's the line that stops the agent helpfully adding a blog, a shop, and a newsletter signup you never asked for.
“我们不做什么”这句为什么非写不可?不写,它会很热心地给你加上博客、商城、邮件订阅。这些一样都没写进去。
The failure this move exists to prevent. It asks, you answer, it asks again, and an afternoon goes by in which the only thing you produced was replies. If all you are doing is copying and pasting between yourself and an AI, you have added nothing. The interview is bounded: it ends when there are two or three approaches on the table. Past that point, if it is still asking and you are still answering, you have stopped directing and started taking dictation. Say propose, and make it bring the options.
这一步要防的就是这个坑。它问,你答,它再问,一个下午过去,你产出的只有回答。如果你做的事情只是在你和 AI 之间复制粘贴,那你没有增加任何价值。问询是有边界的:桌上摆出两三个方案,它就该结束。过了这个点,它还在问、你还在答,那你已经不是在指挥,是在做听写。让它出方案,别自己出。
And give it something to look at. It reads adjectives badly and examples well. If the style, layout or tone you want already exists somewhere — a page, a document, an image, a video — hand that over along with your own content, and say which part of it you want and which part you don't. One reference does more than three paragraphs of description.
另外,给它一个能看的东西。形容词它读得差,例子它读得好。你要的风格、版式、语气,只要在别处已经有一个现成的例子——一个网页、一份文档、一张图、一段视频——就把它连同你自己的内容一起给过去,说清楚哪一部分你要、哪一部分不要。一个参照物顶三段形容。
An agent is a bad judge of its own work. Put what you have in front of other people — ideally people running the other tool — and have their agents read it. In class that means one person's work at a time, everyone reviewing at once. On your own, one other person is enough:
agent 判不了自己的活。把你手上的东西摆到别人面前——最好是用另一个工具的人——让他们的 agent 去读。上课的时候是一次看一个人的,全屋同时看。自己一个人的时候,有另一个人就够了:
Read design.md. You did not write this and you are not the author's friend.
Find the three biggest problems with it: things that are vague, will not work,
or that the author has not thought through. Be blunt. Do not be encouraging.
Once it's a real thing people use rather than a document, assign a person before you assign the task — a parent, a student, someone who arrived from a search and has never heard of you. The angle decides which problems are visible at all: reviewed as “the business”, one page gave back a missing sign-up path; reviewed as “the student” who'd have to use it, the same page gave back a question about whether its author could be trusted. Neither review contained the other. Worked through in session 3 →
等它变成一个真给人用的东西、而不是一份文档之后,先给身份、再给任务——一位家长、一个学生、一个从搜索里进来、从没听说过你的人。角度决定了哪些问题根本能不能被看见:同一页,用「这门生意」的身份看,拿回来的是「没有地方能报名」;用「要用它的那个学生」的身份看,拿回来的是「写这页的人值不值得信」。两份意见谁也不包含谁。第三次课里走了一遍 →
“Do not be encouraging” is load-bearing. Without it you get a compliment sandwich.
“Do not be encouraging”这句是承重的。少了它,你会拿到一份三明治式的客气话。
This is where flattery gets handled. Preference training makes an agent lean towards the answer you seem to want — harmless when you ask it to draft something, useless when you ask it to judge something. You do not fix that by trusting it less. You fix it by asking a different one, and telling that one not to be nice.
“讨好”这件事在这一步处理。训练方式让 agent 倾向于给出你看起来想要的答案。让它起草东西的时候,这没害处;让它评判东西的时候,这就没用了。这个毛病不靠少信它来修,靠换一个来问,并且叮嘱那一个别客气。
Then the part that matters: you rule on each objection. Not the agent.
然后是要紧的那一步:每一条反对意见由你来裁,不是它。
It's right. Change the design.
它说得对。改设计。
It's right, and I'm choosing not to anyway.
它说得对,但我就是不改。
It misunderstood. Here's why it doesn't apply.
它理解错了。这里说明为什么不适用。
It's right, and no version of this thing fixes it — what you're building is the wrong shape.
它说得对,而且这东西怎么改都修不好——你做的这个形式本身就不对。
Add a section to design.md called "Second opinion" with each finding and
what I decided: accepted, dropped, dissolved, or wrong-medium, with my reason.
The fourth verdict is the one worth the whole exercise. A daily planner built as a website has no reminders, no calendar, and nothing to put on a home screen — you have to remember to open it, which is the exact job a planner exists to do for you. Tidying that page cannot fix it; it wants to be an app. Finding that out early is cheap. Finding it out after you've built on it is not.
第四种裁定,值回整个练习。一个做成网站的每日计划表:没有提醒,没有日历,也没法放上手机主屏——你得记得去打开它,而「替你记着」正是计划表的本职。那一页怎么收拾都修不好;它想成为的是一个 app。早发现很便宜,在它上面又盖了一层之后才发现就不便宜了。
This is what the professional version looks like. Real design docs on the instructor's project carry a table titled “Codex consult — findings and disposition” — one row per objection, each marked accepted, dropped, or dissolved by a human. Those three are the set used on code, where nobody is questioning whether it should be software. Wrong-medium is the fourth this course adds. The rule behind all of them: no single model is trusted to be correct, no matter how capable.
专业版长这样。老师项目里的真设计文档带一张表,标题叫“Codex consult — findings and disposition”,一条反对意见一行,每一行由人标上 accepted、dropped 还是 dissolved。那三种是写代码时用的一套,那时候没人在问「这东西该不该是软件」。wrong-medium 是这门课加的第四种。背后那条规矩都一样:没有哪个模型被信任成一定正确,不管它多能干。
Now — and only now — you ask for a plan.
现在(而且只有现在)才去要一份计划。
Turn the approved design.md into an implementation plan in plan.md.
Break it into small tasks. For each task: which file changes, the exact steps,
and how I check with my own eyes that it worked before moving on. Number them.
Put a checkbox on each one. Then stop and let me read it.
Your entire editorial job is refusing tasks that are too big to check. Not writing tasks — refusing them. Go task by task and ask one question: could I check this with my own eyes in about a minute? If no:
你在这一步的全部工作,是拒掉那些大到你验不了的任务。不是写任务,是拒任务。一条一条过,只问一句:这一条我能用自己的眼睛验吗?
Task 3 is too big — I can't check it in one look. Split it.
Do task 1 only. Nothing else. Then stop and tell me exactly what to open
to check it.
Check it. Tick the box. Next task. Never give it five tasks at once — it'll do four well and one badly and you won't know which.
验一条,打个勾,下一条。绝对不要一次给它五条。它会做好四条、做坏一条,而你不知道是哪一条。
Two strikes and you re-plan. If the same task fails twice, stop. A third attempt on a bad plan makes a worse mess than the first two.
失败两次就重新做计划。同一条任务失败两次,停。在一个坏计划上试第三次,比前两次加起来还乱。
Stop. Don't fix it. Explain in plain English what you think the problem is,
and give me two different approaches with the trade-off of each.
That's Move 1 again, scoped small. It's the escape hatch from every death spiral.
那就是第一步重来一遍,范围缩小。这是每一个死循环的逃生口。
The one-task rule is not a beginner's speed limit. A professor in the last cohort, a daily user running research rather than websites, arrived at the same rule without being taught it, and gave the reason more plainly than this page had: let it run ahead and the errors compound, each one laid on the one before, until the work is moving faster than he can hold it. So he takes one step, reads what came back, and only then asks for the next. He has been at this long enough that the slowness is not inexperience; it is what the alternative cost him.
“一次一条”不是给新手设的限速。上一期有位教授,天天在用,做的是研究不是网站,没人教他,他自己走到了同一条规矩上,道理说得比这页更直白:让它跑在前头,错会越滚越多,一个错垒在上一个错上,最后整件事快到他攥不住。所以他走一步,把回来的东西读完,再要下一步。他做这行够久了,这份慢不是生手的慢,是他为快付过账。
The move that separates people who ship from people with a folder of half-built things.
把“能发出去的人”和“一堆半成品的人”分开的,就是这一步。
Don't tell me it works. Tell me the exact steps to see it myself.
The professional version has a name for this and it isn't gentle: “Claiming work is complete without verification is dishonesty, not efficiency.” The rule — no completion claims without fresh verification evidence.
专业版给这件事起了个不客气的名字:“Claiming work is complete without verification is dishonesty, not efficiency.”规矩是——没有新鲜的验证证据,就不许说完成。
Everything above is written by the agent. One exception, and it's short: AGENTS.md — your standing orders, the things you'd otherwise repeat every session.
上面所有东西都是 agent 写的。只有一个例外,而且很短:AGENTS.md——你的常设命令,那些否则每次都要重说一遍的话。
The two tools read different filenames, so put the real rules in AGENTS.md and make CLAUDE.md a single line:
两个工具读的文件名不一样,所以真规矩写进 AGENTS.md,CLAUDE.md 只留一行:
@AGENTS.md
Now both read the same rules and you maintain one file.
这样两个都读同一套规矩,你只维护一份文件。
When to add a line — one trigger, easy to spot: you typed the same correction twice. The second time you say “stop adding sections I didn't ask for,” it stops being a conversation and becomes a rule.
什么时候该加一行?只有一个信号,而且很好认:同一句纠正你说了两遍。第二次说“别再加我没要的段落”的时候,它就不再是一次对话,是一条规矩。
The real harness has gates this course does not teach. Here's the list, so you know what you don't yet know.
真正那套装置里有几道关卡,这门课没教。列在这里,让你知道自己还不知道什么。
The failing test is written and seen to fail before the fix exists. A one-page website has no test suite — your check is your eyes.
先写一个会失败的测试,亲眼看它失败,然后才写修法。一个单页网站没有测试套件,你的检查就是你的眼睛。
Every change reviewed three times in a fixed order. You get one round: your classmates' agents. That's the highest-value one.
每一处改动按固定顺序审三遍。你能拿到一轮:同学们的 agent。那也是最值钱的那一轮。
Code that physically blocks a bad command before it runs. Instructions are enough at your scale.
一段代码,在坏命令跑起来之前物理拦住它。在你这个规模,写清楚规矩就够了。
A server that re-runs everything and refuses the release. Needs a test suite first.
一台服务器把所有东西重跑一遍,然后拒绝发布。这得先有测试套件。
Forced checks against vendor docs before writing config; forced search for existing code before writing new. Both exist because an agent confidently invented something that already existed.
写配置之前强制去对厂商文档;写新代码之前强制搜一遍有没有现成的。这两条存在,都是因为有 agent 非常笃定地发明了一个已经存在的东西。
Testing empty, error, partial, stale, and edge cases — not just the happy one. Steal this one early: “what happens if that's blank?”
空的、报错的、只做了一半的、过期的、边界上的,都要试,不只试顺利那条。这一条早点偷走:“那一栏空着会怎样?”
Two things to take from this. The gap is real — don't leave thinking you've been handed a professional pipeline. And every one of those exists because something went wrong once. That's how yours should grow too: not copied from a book, but added the day something bites you.
这里有两件事要带走。差距是真的——别以为自己已经拿到了一条专业流水线。上面每一条之所以存在,都是因为有人真出过一次事。
Your required homework lives on the session pages — session 1 and session 2. What follows is extra: four things worth doing to any design document, on any project, for the rest of your life.
要交的作业在各次课的页面上,第一次课和第二次课。下面是额外的:四件事,值得对任何项目的任何一份设计文档做,做一辈子。
If one of them goes wrong in a way this page doesn't cover, put it in the course forum. Each session's tips are posted there too.
其中哪一件出了这一页没写到的问题,发到课程论坛。每节课的要点也都发在那里。
Do not build anything while a design is still being sharpened. If your agent starts writing a website, stop it. An approved design comes first, then the plan. Building early is how you end up with something you didn't decide on.
设计还在磨的时候,什么都别造。你的 agent 要是开始写网站,拦住它。先有一份批准过的设计,然后才有计划。早动手是这门课唯一真正的错。
Quit the app completely. Reopen it. Open my-website. Type:
把 app 完全退掉。重开。打开 my-website。输入:
Read design.md. Tell me in one sentence what we're building.
If the answer is wrong or vague, your design is wrong — not the agent. Fix the document and test again until it's right cold, every time.
答得不对或者含糊,是你的设计不对,不是 agent 不对。改文档,再测,一直到它冷着也答得对,每次都对。
The highest-value thirty seconds of the week:
这一周里最值钱的三十秒:
Read design.md. What did I not tell you that you had to guess at?
Ask me about the three biggest guesses.
A classmate's agent challenges your design in class. Do it again at home with fresh eyes — start a brand-new session so it has no memory of writing the thing:
课上是同学的 agent 挑你设计的毛病。回家换一双新眼睛再来一次——开一个全新的会话,让它对写过这份东西的事毫无记忆:
Read design.md. You did not write this and you are not the author's friend.
What is the single biggest reason this website will disappoint the person
who ordered it? Be blunt. Do not be encouraging.
Rule on it yourself — accepted, dropped, dissolved, or wrong-medium — then have it recorded in the file.
自己裁(accepted、dropped、dissolved 还是 wrong-medium)然后让它记进文件里。
AGENTS.mdSomething that actually annoyed you this week. The trigger is simple: you said it twice.
这一周真让你烦到的某件事。信号很简单:同一句话你说了两遍。