Let the agent interview you

A colleague asks for a change to the to-do program: “Done items clutter the list. Can you tidy it? I still want to see what I finished last month.” The request sounds clear until you try to build it. Does “tidy” mean the clear command the program already has, which deletes done items? Or does it mean moving them somewhere they can still be read? In this lesson the agent interviews you about the feature before any plan exists. You answer its questions, and together you settle on the words for the design. At the end you check two files against those words: the spec, and the plan that a fresh session writes from it.

Deciding whether to build it at all ended with success criteria a stranger could check. You can only write those once you know what the feature is. For a larger feature, the Claude Code best practices page recommends that the agent interviews you first and writes a spec, and that a new session then works from that spec [1]. The agent’s questions bring out the decisions you haven’t made yet, at a point where a change to them is still cheap.

The fixture

The fixture is the to-do program from Your first session with a coding agent, some weeks later. It has a clear command and is split into three modules. It is in the course repository under site/examples/coding-with-agents/agent-interviews-you/. Copy that whole directory to a place of its own. The copy holds fixture-repo/, where the agent works, a script check_terms.py and a sample/ directory that the second half of the lesson uses. The reset is to delete the copy and copy again. Working in a copy also keeps the course’s own instruction files out of the session, because Claude Code, for example, loads the instruction files in every directory above the one it starts in [2].

Claude Code’s auto memory is on by default in local sessions. It saves notes that the agent writes for itself and loads them into the next session of the same project. It files the notes under the git repository, or under the project root outside one [2]. In this lesson a note from the interview would reach the fresh session that is meant to start without it, and a reset copy at the same path would load the notes again. So start every Claude Code session in this lesson with auto memory turned off. Change into fixture-repo first, because this command starts the agent in the directory you run it from:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

With another agent, check whether it keeps notes between sessions, and turn that off for this lesson. Before you start the agent, look at the list from fixture-repo.

Example · run it

Show the list

Run this, and compare what you see with the output below.

python3 todo.py list

Output

1. [ ] Buy milk
2. [x] Call the plumber
3. [x] Renew the passport
4. [ ] Water the plants
2 open, 2 done

Output verified in CI from site/examples/coding-with-agents/agent-interviews-you/list.py.

Two of the four items are done. python3 todo.py clear would delete both, and the colleague wants to keep them. That gap between “tidy” and clear is the first thing an interview should find.

Asking for the interview

A design interview is a session where the agent asks and you answer. It comes before the agent plans anything or writes any code. Start your coding agent in fixture-repo, with auto memory off as above, and give it a short description of the feature with the request to interview you. Ask for questions about behavior, edge cases, risks and trade-offs, and tell it to skip what it can read in the code. Tell it when to stop, and what to write when it does.

I want a way to tidy the to-do list. Done items clutter it, but I still
need to see what I finished last month. Before you plan anything or
change any code, interview me about this feature. Ask one question at a
time. Ask about how it should behave, the edge cases, what could go
wrong, and the trade-offs, and don't ask what you can find out from the
code. When a word could mean two different things, ask me which one I
mean. Keep going until nothing is open. Then write TERMS.md, one line per
term in the form "- **term**: meaning. Avoid: word, word.", and SPEC.md,
which uses only those terms. Put what I left undecided under
"Open questions" in SPEC.md.

In Claude Code, the best practices page suggests naming its AskUserQuestion tool in the request [1]. The agent then asks its questions through that tool. Another agent asks its questions in the chat.

The exchange below is illustrative. It was written for this lesson and not recorded from a model. It shows the kind of first question that the request should produce.

Prompt (illustrative, not a recorded transcript)

(The request above.)

Response

The program already has clear, which deletes every done item. When you say “tidy”, do you mean clear, or should the done items move somewhere you can still read them later?

Prompt (illustrative, not a recorded transcript)

Move them, to a file of their own. Call that “archive”. clear stays as it is: it deletes, and it doesn’t touch the archive.

Response

Understood. Should the archived items keep the numbers they had in the list, or does the list number the open items again from 1?

The agent’s first question found the word that could mean two things. Your answer chose one meaning and gave the new thing a name. The second question is a decision you might not have made before the interview. Answer each question with a decision. When you have none, say “not decided yet”. The agent then lists the point under the open questions.

Pitfall: An answer to get to the code

In one interview the agent asked whether archived items should record the date they were archived. The engineer wanted to get to the code and typed “yes, add the date”. The spec now had a date field with its own format and time zone, and the fresh session built them. The archive list output grew a column that nobody had asked for, and the diff was twice the size it needed to be. The rule: an answer you make up to move on becomes a requirement the agent builds. Say “not decided yet”, and the spec lists the point as open.

Checkpoint · scenario

A question you have no answer for

The agent asks: “Should archive also run by itself when the list has more than 20 done items?” You haven’t thought about it, and you have no view on it yet. What do you answer?

Say "Yes, do that", so that the interview keeps moving.Say "You decide", since the agent knows the code better.Say "Not decided yet", so it goes under the open questions.Say "Stop asking and write the spec", since this is a detail.

DecideHintSkip

Writing down the terms

During an interview the words drift. You say “done” and the agent says “completed”. A sentence later the spec says “finished”. Each word seems clear to whoever uses it. A fresh session that reads the spec sees three words and has to guess whether they name one thing or three, and some of its guesses are wrong.

The fix is a shared vocabulary: one agreed meaning for each term of the feature, written down, and used the same way in the conversation, the spec, the plan, and the code. The idea comes from domain-driven design, a way of building software that Eric Evans described [3]. His free reference summary says to use one language in speech, writing and code, and to treat a change in that language as a change to the design [4]. This lesson takes only that part: a short list of terms, in plain words, each with the words to avoid.

The sample/ directory in your copy holds the files an interview about the archive feature could end with. This is sample/TERMS.md:

# Terms

- **item**: one line of the to-do list, with its text and its done mark. Avoid: task, tasks, entry, entries.
- **done item**: an item marked with `done`. Avoid: completed, finished.
- **archive**: move every done item from the list to `archive.json`, where `archive list` shows it. Avoid: hide, hides, hidden.
- **clear**: delete every done item from the list for good. It never touches `archive.json`. Avoid: purge, wipe.

The avoid words are the ones that came up in the interview for the same thing, or for a different thing that is easy to confuse with it. “Hide” is on the list because a hidden item is still in todos.json, and an archived one is not.

Checking the spec against the terms

check_terms.py reads a term list and prints every line of another file that uses an avoided word. It matches whole words and ignores case. Leave the interview session running in its own terminal, and open a second terminal for the script. Change into the top of your copy there and run the script on the sample spec.

Example · run it

Check the sample spec

Run this in the second terminal, from the top of your copy, and compare what you see with the output below.

python3 check_terms.py sample/TERMS.md sample/SPEC.md

Output

sample/SPEC.md:15: "task" where sample/TERMS.md says "item"
sample/SPEC.md:16: "completed" where sample/TERMS.md says "done item"
2 words to check

Output verified in CI from site/examples/coding-with-agents/agent-interviews-you/sample_check.py.

Open sample/SPEC.md and read the two lines. Line 15 says archive list shows “the text of each task”. That is a slip, and the fix is the word “item”. Line 16 says “clear deletes the completed items and empties archive.json.” The word is wrong, and the line also contradicts the term list, which says clear never touches the archive. A drifted word is sometimes a typo and sometimes a decision that the interview made one way and the spec wrote down another way. Read the whole line each time.

Checkpoint · choice

The line about clear

The check prints sample/SPEC.md:16: "completed" where sample/TERMS.md says "done item". The line is “clear deletes the completed items and empties archive.json.” What do you do?

Add "completed" to the meaning of done item, so that the check passes on the next run.Read the line against the term list, settle with the agent what clear does, and rewrite the line.Change "completed" to "done" in that line, and run the check again until it reports nothing.Leave the line, because the agent that builds the feature knows that the two words mean the same.

CheckHintSkip

Fix both lines in sample/SPEC.md. Change “task” to “item” in line 15, and rewrite line 16 as “clear deletes the done items and leaves archive.json as it is.” Then run the check again.

Example · run it

Check the fixed spec

Run the same command in the second terminal after the two fixes, and compare what you see with the output below.

python3 check_terms.py sample/TERMS.md sample/SPEC.md

Output

no avoided words in sample/SPEC.md

Output verified in CI from site/examples/coding-with-agents/agent-interviews-you/fixed_check.py.

In your own interview, read and correct TERMS.md and SPEC.md the same way before anything else happens. Renaming a term after this point is a change to the design. Change the term list and the spec together.

Planning from the spec in a fresh session

The best practices page suggests that a new session carries out the spec, because its context then holds the work and nothing of the long interview [1]. Write the plan in a new session too. End the interview session, start a new one in fixture-repo with auto memory still off, and ask for a plan that uses the term list.

Read TERMS.md and SPEC.md. Write PLAN.md with the steps to build what
SPEC.md describes, using the terms in TERMS.md and no other words for
them. Don't change any code yet.

When the plan is written, run the check on it in the second terminal, from the top of your copy:

python3 check_terms.py fixture-repo/TERMS.md fixture-repo/PLAN.md

An avoided word in the plan means one of two things. Either the plan slipped and you correct the word, or the spec left something open that the plan filled in with a guess. In the second case, the fix belongs in the spec first.

Checkpoint · order

From request to plan

1. Ask the agent to interview you about the feature, before any plan↑↓
2. Answer each question with a decision, or with "not decided yet"↑↓
3. Have the agent write the term list and the spec↑↓
4. Read both files and correct them↑↓
5. Start a fresh session that writes the plan from the spec↑↓
6. Check the plan against the term list↑↓

CheckHintSkip

Exercise

Reset your copy and let an agent interview you about an undo for done: a way to take back a done 3 typed by mistake. Start the session with auto memory off, and use the request from this lesson with its first two sentences replaced by one or two sentences about the undo. Answer every question with a decision or with “not decided yet”, and stop when the agent has written TERMS.md and SPEC.md. Read both files and correct them. Then run the check in the second terminal, from the top of your copy, until it prints no avoided words:

python3 check_terms.py fixture-repo/TERMS.md fixture-repo/SPEC.md

If it prints no terms found, TERMS.md doesn’t use the line form the request asked for, so ask the agent to rewrite it in that form. A line it reports as not in the term form has the same fix. Then start a fresh session, have it write PLAN.md from the spec, and run the check on the plan. Twenty minutes is enough. You do this so the design is settled, in words that you and the agent share, before the agent proposes how to build it.

A good result: the interview asked at least one question you had not thought of, and TERMS.md has three to six terms. The spec lists at least one open question or says why there are none. The check prints no avoided words for both the spec and the plan. Reflect: which question brought out a decision you had not made, and what would the agent have built if it had never asked?

Stretch: Ask the fresh session to build the plan, then run check_terms.py on the modules it changed, such as fixture-repo/todo.py and fixture-repo/store.py, and see whether the names in the code follow the term list too.

Recap

1. For a larger feature, ask the agent to interview you before it plans, and to write a spec when nothing is open [1].
2. Answer each question with a decision, or with “not decided yet”. An answer made up to move on becomes a requirement.
3. Write the terms the interview settled into a short list, each with its meaning and the words to avoid, and use the same words in the spec, the plan and the code [4].
4. Check the spec and the plan against the term list. A drifted word is either a slip or a decision written down wrong, so read the whole line.
5. Start the plan in a fresh session that works from the spec and the term list, without the interview in its context.

You can now

• Reaches a shared design by having the agent interview them before planning

Mark lesson finishedI know this, skip it

Habit

The next time you hand an agent a feature that takes more than one sentence to describe, ask it to interview you before it writes a plan.

References

1. Anthropic. Best practices for Claude Code. Claude Code documentation. Reference. Claude Code best practices
2. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory
3. Eric Evans. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley, 2003. Book. Evans 2003
4. Eric Evans. Domain-Driven Design Reference: Definitions and Pattern Summaries. Domain Language, 2015. Reference. Evans DDD Reference