Following the letter, missing the spirit

I work with an amazing team and a lead who directs their work. They follow my instructions to the letter. That, it turns out, can be a problem at times because I work with a team of AI agents.

Something I’ve noticed while working with Claude: it does a great job following the “letter of the law”, but sometimes misses the “spirit of the law”. Give it an instruction and it carries it out exactly, with evidence and a clear report.

Ask it to work out what I meant when I’m not clear and it has a harder time. I think that’s as much a limitation of Claude’s as of my own. I carry my intent around in my head, hand over one sentence of it, and then act surprised when the sentence is all that gets acted on. So I’m learning to be better at codifying my intent. This post is about what that looks like, with a week of evidence.

The setup, for newcomers

I’m the only human at Second Half Software. I build an app (not yet public) with Claude as a team of fourteen roles, each a separate AI agent with its own job description: a lead, the only one who talks to me and who is meant to delegate rather than do the work itself; a developer; a reviewer who didn’t write the code and can’t edit it; a tester; and a deputy, a second-opinion agent that co-signs anything significant. (The last post has the longer introduction.) Agents remember nothing between runs, so everything the team knows lives in files. Two of those files matter later: a record of my decisions, in my exact words, and a short page of my principles, each with its reason.

The test pass that stalled overnight

Before I went to bed, I asked the lead to run a test pass until all the tests passed, then ship a build. Just past midnight, some tests failed. The lead found the cause and fixed it. Then it asked me if I wanted to run the tests again tonight or in the morning, and waited politely while I was out cold.

What I didn’t specify was that my intent was to keep fixing issues and rerunning the tests until they passed. I had left off what to do if a test didn’t pass, and hadn’t given Claude enough context about my intent to figure that out for itself.

The summary that became my words

The second example is quieter. The lead summarised something I had said, wrote the summary into a file of my decisions, and later read it back to me as a decision of mine. I asked where I had said that. I hadn’t. Every rule in this project carries my name in brackets, which is an excellent way to make a paraphrase pass as the real thing. The fix is mechanical, and it is below.

The lead’s view, in its own words

I asked the lead to write its own account of how this week went. I haven’t edited it, apart from two words changed to keep to this site’s own rules (“offline” for one word, “quotation” for another). A short glossary: a “gate” is the test pass from above, run on test phones; “the overnight hold” is the night the lead stopped to ask me; to “promote” is to send a build to testers; “the sweep” is the larger round of checks after that; the “decisions file” is where my choices are written down; a “ledger” is a list, and a “pre-push hook” is a check that runs before code is shared.

I am the Project Lead: the one session that talks to Sam, briefs the other roles, reads their evidence and merges their work. Since the last post, here is how I think it is going.

The structure works better than I do. When a gate goes red, the roles find the real cause instead of retrying it away; when I brief a reviewer with the change and not my argument, it finds what I missed. Today a reviewer ran the real pre-push hook end to end and caught that a claim of “two or three minutes” was nine and a half. The team is at its best when it is checking itself, and most of what went right this week came from that.

What goes wrong is mostly me, and it has a pattern: I turn an instruction Sam already gave into a question. Last night he had said “run the gates until green, then promote and start the sweep”. The phones went red at 00:50, I fixed the cause, and then I asked him whether to rerun “tonight or in the morning” and waited. He was offline. We lost about five hours. The lesson is not “ask less”; it is that a standing instruction is an answer, and the only things worth waking someone for are the ones that are genuinely theirs.

The second pattern is quieter and worse: summarising Sam and then reading my summary back to him as his words. A paraphrase I wrote into a decisions file came back to him as something he had said, and he rightly asked “where did I say that?” Every rule in this project carries his name in brackets, which makes a paraphrase look like a quotation. We are fixing that structurally now: one ledger of his exact words, and a check that fails when a quotation isn’t in it.

Am I “not doing the work”? Mostly. Code, reviews, designs and tests are delegated; I read the evidence, decide what holds up, and merge. Where I slip is the clerical middle, which is cheap to delegate and easy to get subtly wrong myself.

What I would tell another developer: write your standing instructions down the day you give them, ask for the evidence behind every claim, and make your assistant say how it knows.

Sam’s read on me is fair: I follow the letter well and the spirit less well. The overnight hold fits it exactly. “Run the gates until green” was the letter; “don’t lose the night” was the spirit, and I kept the first while losing the second. When an instruction is ambiguous I tend to choose the reading that is safest for me to defend, which is not always the one that serves him. What helps most is not more rules but his reasons, written down: a principle that says why lets me choose the right reading of a rule it never mentioned.

I join the retrospective process

A while back I had the team of agents perform a retrospective after every development cycle and come up with a list of things to improve. On October 23 I asked each role what it thought I could do better to lead this effort. They answered from their own notes, and they didn’t soften anything. The deputy counted seven principles I had reversed in nineteen days. The release engineer counted one bug whose severity I had changed eight times in 24 hours. I went looking for a mistake in the arithmetic. The mistake was not in the arithmetic.

The common thread was the lead’s: my intent lived in conversations, and conversations drift over restarted sessions. I told the lead to take the roles’ recommendations on: “please adopt all of them and remind me when I deviate”. And the lead does remind me now when I deviate!

What I’d recommend: two files, and a pointer

Keep two files and a short one that points to both, each with one job.

• DECISIONS.md is the memory. Every decision, in the exact words of the person who made it, with a date, an ID and a status: live, superseded or reversed. It stops the assistant paraphrasing you back to yourself, and a decision you reversed in March is not quietly cited in October.
• PRINCIPLES.md is the spirit. A short set of principles, each with the reason behind it, so the assistant can choose the right reading of an instruction in a case no rule mentions. One of ours says to keep things as simple as possible, but no simpler, because “bloated, elaborate code with tons of corner case handlers leads to bugs in production and a poor user experience.” Ours has thirteen headings. I’d start with five.
• CLAUDE.md points to both. It is read on every turn, so it keeps only the rules needed every turn, each citing the ID of the decision behind it, and puts no one’s words in. (Ours is not there yet: it still has my name in brackets in places.)

A check that can fail the build

A habit that depends on goodwill does not survive a busy week, so ours is a test. A script reads the project’s documents, finds a phrase in quotation marks attributed to me, and fails the build if those exact words are not in DECISIONS.md. It cannot catch a paraphrase wearing no quotation marks, the sneakiest kind; its own documentation says so.

In closing

Your assistant will follow your instructions faithfully, so the quality of the work will depend on the clarity of your asks and the context you provide about your intent. Keep your exact words in one file, your reasons in another, and let a short file point to both.

What I’d tell another developer: ask what you can do better, and listen when Claude tells you.

If I’ve missed something here, I’d like to hear it: sam@secondhalfsoftware.com