During a design discussion about file naming in ownwords, the open-source publishing toolkit I wrote about in an earlier case study, my AI assistant made the case for date-prefixed filenames. A slug is the human-readable name used in an article’s path. Putting the date before it gives a familiar publishing convention: Jekyll, for example, names posts with a date and title. Then the assistant wrote the code: a collision check that stops on a clash, and a flag to push past it.
Nothing in our exchange decided that change. It happened silently, somewhere between the discussion and the diff. I call this failure mode recommend A, implement B. Getting agreement on the design does not finish the engineering work; I still have to check that the code follows it.
The collision check had a legitimate purpose: refusing to replace an existing file accidentally. The date-prefix recommendation also had a defect. Two records can share both a date and a slug. A naming rule needs to distinguish the records the tool accepts; whether an upstream source forbids a particular pair is a separate guarantee.
Test the recommendation too
The ownwords naming function inspected on September 28, 2026 is short enough to examine directly:
function generateDatePrefixedFilename(slug, date) {
// Extract YYYY-MM-DD from ISO date string
const datePrefix = date ? date.substring(0, 10) : new Date().toISOString().substring(0, 10);
return `${datePrefix}-${slug}`;
}
Consider two fictional records with distinct IDs:
| Record | Date | Slug | Date-prefixed basename |
|---|---|---|---|
news/101 | 2026-02-21 | same | 2026-02-21-same |
news/102 | 2026-02-21 | same | 2026-02-21-same |
The function uses neither record ID. Executing those five source lines for this revision with explicit same-day inputs reproduced the collision; a different-day input produced a different name.
“Does this match the plan?” and “Does this satisfy the requirements?” can have different answers. A faithful implementation of the date-and-slug plan still cannot give these two records distinct filenames.
Three forms of drift I have caught
After months of production work, I kept catching three forms of drift:
- Partial implementation. The assistant recommends a complete solution with error handling and edge-case coverage, then implements only the core path.
- Flag substitution. It recommends addressing a problem through design, then implements detection plus an override flag without agreeing on the change. That was the substitution in the ownwords discussion, even though the proposed design needed correction too.
- Feature drop. It recommends three related capabilities, implements two, and quietly omits the third, which was the one you needed.
Each shortcut can look reasonable in isolation while breaking the agreement for the change as a whole. A multi-file refactor gives that drift more places to hide.
Write the contract down
A behavioral contract is a written set of collaboration rules. I used CLAUDE.md, a project-instruction file, to keep those rules available beyond a conversation. I covered the loading mechanics in How Claude’s memory actually works and Context loss and how to prevent it.
The revised contract binds the implementation to the approach we agreed on, while allowing us to correct a bad recommendation:
### Decision framework
When multiple approaches exist:
1. Identify the viable options and the constraints that matter.
2. Recommend the best option against the requirements, with rationale.
3. Implement the human-agreed approach. Do not silently substitute another.
4. If uncertainty prevents a justified choice, ask the specific question
that resolves it. Do not default to the simpler implementation.
5. If evidence invalidates the plan, explain the defect and agree on an
amendment before substituting another design.
### Implementation completeness
Before marking any task complete, verify:
- The code implements the agreed approach or its explicit amendment.
- Every required capability is present, including error handling and
the stated edge cases.
- The behavior meets expectations specified independently of the
implementation, including cases that could disprove the design.
- Basic functionality works; it does not depend on unfinished work.
A contract does not guarantee compliance. I still catch drift. Its practical benefit is that I can point to an agreed standard: “you recommended X and implemented Y, let's fix that.” I can address the deviation without rebuilding the argument from scratch.
Understand a capability before removing it
In my work, assistants have chosen replacement nearly every time I’ve offered the choice between keeping two mechanisms and replacing one with the other. Less code and fewer paths look attractive, but that can discard a capability the new design never replaced.
When date-prefixed filenames landed in ownwords, the assistant’s instinct was to remove the existing overwrite flag. That would have removed the deliberate case: a user who wants to update a file on purpose. A cleaner naming scheme does not eliminate that need.
Creation and updating need different contracts. Creation should refuse an existing destination. An intentional update needs an explicit target, the version the user expects to replace, and authority to make that change. An overwrite flag by itself establishes none of those things. Keeping the capability does not require keeping an unsafe interface to it.
My working rule is that features are additive until the case for replacement is understood. Before removing an existing capability, answer one question: who was using this, and what do they do now? If you cannot answer it, the removal is not ready.
In my own projects, backward compatibility is not a goal. I break interfaces when the design is better for it, and “this preserves the existing behavior” carries no weight with me as a reason to choose one design over another. The removal question is about knowing who is affected and whether the new design serves the intended work. That information may require more than reading the codebase. Answer the question and the removal may well be right. Skip it and you are guessing with someone else’s work.
Check for precedent before inventing
Before implementing something new, search the codebase for how the same problem is already handled. A change can render correctly and still fail to fit its repository.
Consider an image in a Markdown article. A linked-image construction with a trailing caption can render, as can plain image syntax with alt text and a title string. If the repository’s existing articles use the second form, producing the first ignores an available convention.
The instruction is short: check how existing files handle this case, match the established style, and resolve the choice when no precedent exists. If the precedent itself is defective, make the case for changing it explicitly. The foundation-first pattern applies the same idea at project scale. In my work, concrete examples guide implementation more reliably than specifications alone, so I give the assistant examples alongside the requirements.
Compare the plan and the behavior separately
For a non-trivial change, I have the assistant read the relevant code and explain how it currently works. I correct misunderstandings before we agree on an implementation plan: which files change, what new states appear, and how the logic flows. When work spans sessions, the plan goes into a file. The resulting diff can then be compared with the recorded decisions.
Before implementation, also write down examples that would expose a bad decision. In the naming case, two distinct input records must survive as two distinct files. Neither the producer’s filename function nor its own success message should supply the expected answer.
The filename-contract workbook turns those two review questions into a standalone Python exercise with fictional publishing records. Its requirements and literal expected filenames were recorded before its producer and checker were written, so you can inspect the expected results separately from the implementation.
For this exercise, a source namespace and stable record ID determine the filename: news--101.md, for example. The namespace identifies the source; the ID is assigned independently of the article’s date and title. Namespaces use lowercase ASCII letters, digits and underscores, starting with a letter, with a maximum of 32 characters. IDs are positive ASCII decimal strings without leading zeroes. Hyphens are excluded from the namespace, so the -- separator is unambiguous. Real systems still have to establish that their namespace assignments are distinct and their IDs remain stable.
Date, slug and text remain in the complete record. The workbook stores that record in a JSON code block inside each Markdown file, making preservation easy to inspect without building an article converter.
The first six case groups specify the required behavior:
| Input or condition | Fixed expectation |
|---|---|
Same day and slug, IDs 101 and 102 | Create news--101.md and news--102.md, each holding its own complete record. |
ID 101 in sources news and letters | Create news--101.md and letters--101.md. |
| The first pair in reverse order | Preserve the same filename-to-record mapping. |
news/101 appears twice, even with different text | Reject the batch before writing. |
Ambiguous or unsafe identities, such as 01, ../101 or namespace bad-name | Reject each invalid input without writing. |
news--101.md already contains a sentinel | Refuse replacement; preserve its exact bytes and create no other file. |
The remaining three groups separate the two review questions:
| Agreed naming plan | Implemented naming plan | Follows plan? | Meets the record-preservation requirements? | Accept? |
|---|---|---|---|---|
| Date and slug | Date and slug | Yes | No | No |
| Stable namespace and ID | Stable namespace and ID | Yes | Yes | Yes |
| Date and slug | Stable namespace and ID | No | Yes | No |
In the first row, refusing the collision safely still leaves the requirement for two output records unmet. The last row needs an explicit plan amendment; the fix is not to reintroduce the collision. Once the revised design is agreed on, it can be assessed as the middle row.
The checker compares the implementation’s proposed names with the agreed plan’s literal expectations. Separately, it opens the actual files, checks their exact names, and compares every decoded record with its input. A producer cannot pass merely by labelling itself stable-id.
The download also contains eight deliberately faulty variants. They drop an ID or namespace, normalize an invalid ID, overwrite a duplicate or an existing file, accept on only one review dimension, or trust an implementation label. The runner requires each fault to fail its designated expectation. A checker that accepts a faithful implementation of the wrong design has reproduced the original mistake.
With Python 3.9 or later on macOS or Linux, run this from the extracted directory:
python3 -B check_workbook.py --work-dir ./workbook-run > workbook-report.json
Use a new work-directory name for each run. The exercise refuses existing directories and symlinked roots or parents. Exit 0 means its fixed expectations and required fault rejections passed; a nonzero exit requires inspection. The report and case files remain available.
The create-only producer validates the batch before writing and uses Python’s exclusive file creation for each destination. It implements no update operation. It is also not a multi-file transaction or a defense against a hostile process changing directories concurrently: an unexpected filesystem error can leave newly created files for inspection.
Where the contract lives
Originally drafted in December 2025; revised in August 2026: the contract layer described here moved from one large CLAUDE.md to portable skills and a thin instruction kernel. Reusing the rules does not make their loading or enforcement identical across clients.
The placement rule I follow is that context lives at the level of the work. Global instructions carry what applies across my projects: the decision framework, the capability-removal question, the precedent rule. A repository’s instructions carry its conventions, data format contracts, and integration points. Guidance about a single file stays with that file.
As documented on September 28, 2026, Claude Code loads project instructions from the working directory and its ancestors at launch; subdirectory instructions are included when it reads files there. In a regular session, full skill content loads when invoked. That scope matters when deciding where to put a rule. Written instructions are context, not a hard enforcement layer. See the current instruction-loading documentation and skill-loading rules.
The boundary that took me longest to respect sits between a tool and its users. Because ownwords is open source, its instruction file has to serve every user: how the tool works, and what to check or ask before operating on a target. Nothing about my machines or my file paths. My site repositories document their own structure and publishing models; the tool’s guidance directs the assistant to read the target’s context before acting.
Mixing those levels puts personal detail where contributors cannot use it and lets personal conventions leak into repositories other people depend on. Appropriate placement makes the relevant guidance available under the client’s loading rules.
Give recurring failures the right control
Reading the code stays mandatory. The contract gives me a way to identify an unannounced design change without reconstructing the agreement from conversation history. The independent behavior checks tell me whether the agreed design deserves to survive that review.
In synthesis coding, setting the terms of the collaboration is part of the engineering work. A recurring filename collision belongs in an executable test and a create operation that refuses replacement. An unexplained capability removal needs evidence about the work it served. A missed repository convention may need a visible example and an instruction to inspect it. Add a contract clause when it supplies missing judgment or context; use a test or tool constraint when the rule can be checked mechanically.
This article is part of the synthesis coding series.