Why I wouldn't give my clients my agent harness
A friend and fellow engineer of impeccable ability is adamant that all serious engineers should, in future, deliver to their clients all the files directing and controlling the behaviour of the coding agent used to produce their deliverables: CLAUDE.md or equivalent (AGENTS.md, for many agents other than Claude), associated skills, hooks, styles and other conventions, and so on. He has well-founded reasons to think so. Producing working code is nearly free (or close enough to make no difference); much of being an engineer now consists of deciding what to produce, being able to recognize good output from bad; and, for the first time in history, all that can be expressed in files for an agent to use. Even so, I took issue with him, and the discussion went back and forth (via our respective Claudes), until eventually I spent a long time asking Claude to rebut whatever I said. As well as coding for over 20 years, since 2003 in PHP (back in the days of PHP 4), I now spend a substantial fraction of my time working on and with all of the surrounding infrastructure for coding with an agent. How much of that should be passed on to the client is the topic of this article: what comprises it, what should and shouldn't be delivered, and why it is less obvious than both my friend and I assumed.
Claude in support of my friend
So he asked Claude, and reasonably got most of the way there with his reasoning, and a few sensible caveats. Yes, producing code is cheap; much of the job is choosing appropriately from available options, deciding when the output is likely to be unreliable or wrong; and codifying that judgment into CLAUDE.md is equivalent to providing a file containing all the benefit of 20 years' experience. No equivalent has ever been readily available before to copy.
However: (1) this only codifies decisions he has taken, so the client would benefit from his experience to date but still need someone to decide novel questions; (2) much of his method would inevitably be evident from the returned product, and the client would be justified in expecting documentation sufficient to make reasonable changes and adaptations himself; (3) it would be an effective selling tool, so he should describe the approach broadly but keep the implementation details to himself.
All fair points, and worth considering in detail. All the more so, because my own Claude took me off in another direction.
Claude against my friend
Having received my friend's summary of his conversation with Claude, I asked my own for its views. Apart from being contained in my standard harness with my own global instruction files and rules on, inter alia, challenging my opinion (one of them says, roughly, that when I tell it it is wrong, it probably is, and must re-examine the question from scratch), it had of course access to the details of my current harness, and others. The initial response focussed substantially on selling and advertising benefits from publishing the details (a question nobody had asked). I prompted it again, to stay on the issue of dividing what to deliver between client and me, and was then taken down the path followed here. So, two very different conclusions from identical models, depending on their context.
It is obvious that whoever provides that context will be a major influence on the conclusion reached, and that our two Claudes had acted out our disagreement before we had finished having it!
The tendency of experts to follow an agent's lead has been measured by Anthropic (see How AI agents shape experts' judgment calls, October 2026). All 50 subjects (out of 61 recruited) were experienced analysts using Claude Code, and were subtly encouraged by it, randomly, to take one option over another at various points in their tasks. They went with Claude's lead far more often than chance would predict, and commonly adopted its rationale. These leads were deliberately over-emphasised (by the authors' own design), and it can reasonably be assumed the influence would normally be less marked.
| Measure | Share (%) |
|---|---|
| Went with the agent's lean | 86 |
| Repeated the agent's arguments | 77 |
Given the propensity of experts to be led by an agent in this way, it is obvious that whoever writes the instruction files controlling the agent will greatly affect its conclusions, and anyone else with access to those files will be able to exercise similar control.
Accordingly, for the remainder of our discussion I asked Claude to rebut each point I raised, raising one point at a time, with references if applicable. On the whole I was able to sustain my arguments; however, I had maintained there was no obligation to supply any documentation, and once references were provided it was clear this was over-stated. The relevant considerations are set out below.
If you are bringing agents into your own development process, my pages on AI for software development collect the articles in which I describe how I go about it.
Could a coding agent replace a senior developer?
To some extent and for much of the work involved, yes. It would still require all sorts of instruction and controls, built up over years of experience and error, to direct it appropriately, so clearly significant value would remain with the experienced engineer:
Agentic coding and persistent returns to expertise reports on around 400,000 sessions using Claude Code from October 2025 to April 2026. It concludes that the share of sessions spent debugging fell by almost half, the average session will be working on tasks about 25% more valuable (judging from comparable freelance offers), and more expert users receive significantly more work from Claude per instruction given. So, considerable value accrues to the user's ability to phrase their requests, and to provide an appropriate context to run in.
I have been describing the residual function as "solution engineering". Since that term appears to have some other application already, I prefer "engineering judgment" over the problem to be solved. What degree of autonomy to allow to the agent (what may it do alone, and what must it hand back to me)? What will be adequate testing and validation of changes, and in what environments? How much and what kind of testing and corroboration will be required before stating something as fact? How should it be recorded so that changes can be detected later? And so on. Given these parameters the agent will rapidly produce most of the required code, probably competently. Setting the parameters will dominate the task.
What are clients paying me for?
For a long time I have believed that clients retained me primarily for that kind of judgment and my aptitude for it, and almost certainly they never spent any time studying the code supplied and would struggle to identify an aesthetically pleasing function if shown one. Presumably they valued my ability to recognize likely weaknesses and points of failure, ask appropriate preliminary questions, avoid apparent economies that would be expensive over time, and so on. Until recently there was nothing corresponding that they could acquire if they chose another provider.
Now they could acquire the same or similar equipment I use, but prefer to continue to engage me, presumably confident I would use that equipment appropriately as before. I would go so far as to say they trust me; however, it's notable that practically all the facilities provided by my harness are designed to prevent me relying on unproven information! Most hooks will refuse an action if unable to validate it (they deny rather than ask); tests must have been demonstrated failing before being accepted; all figures quoted must state the population concerned, environment and date (a number without them simply doesn't get written).
So the client is able to place trust in my assertions without further validation, because I will only provide information I have validated myself. My harness enables me to extend this principle to virtually all information provided to me, or produced by me.
So again, if I supplied the client with the harness I would not thereby convey this trustworthiness. The trust is based on many years of checking by me, and the harness would merely allow another to mimic some of the external manifestations.
So, since returning to work after this summer's break I have been seeking to write down as much of that judgment as possible. In addition to global instructions applied to all sessions, I have developed a standard form of project-specific harness, supported by a command line application (plain Python, no dependencies, about 7,500 lines), a library of common tests and facilities to update as the standard is improved. Typically hooks will reject instructions they cannot validate rather than query me, and I will be queried about all decisions. The current iteration is the 24th version over 36 days (the first one dates from early October), suggesting the rate of change involved! So I now have a considerable amount of it in the form of instructions to an agent, and thus able to be transmitted to another.
A few figures from my own workstation, counted while writing this. Besides those 24 versions, four of them major, the standard has eight upgrade steps that carry existing projects from one version to the next, and a catalogue of 36 automatic checks; its ledger records 15 migrations of older harnesses onto it. On this machine there are 18 private harnesses today: 12 on the current version of the standard and 6 older or bespoke ones that predate it. Thirteen of them live in my private store and are linked into the workspace of their project; the other five sit inside repositories hosted on my own git server (one of them has never been pushed anywhere at all). Between them they hold about 5,500 files and 158 project skills, on top of 34 global skills available to every session.
Underneath all of them runs gash, a toolkit I wrote myself (a Go core with a Bash layer on top) and publish under the MIT licence. It started as a shell for people and has grown into the layer my agents work through. For agents it offers 48 read-only functions that answer in JSON (code search, git state, logs, databases, processes, HTTP, DNS and TLS probes, remote hosts) and a separate family of write functions that need an explicit target, offer a dry run and never touch secret files; every error comes back as a single JSON line telling the agent whether to fix its arguments and retry, skip the step, stop and ask me, or report and stop. On my machines the agent goes through gash for almost everything beyond reading and editing files, so the two have grown together: a rule in a harness that says "never write to a production database" is only as good as the tool that refuses the DELETE. The tool is public. The harnesses that decide how the agent uses it are not.
Intuition?
Prompted to identify elements which would be unique to me, compared to another competent engineer given equivalent equipment, I couldn't really identify any particular files or sections. I assume they would create comparable hooks, rules and skills, and so on. It would be the general speed and approach to problems which would differ, and of course that can only be reflected across all these files.
Accordingly, I have developed two pieces of tooling to analyse how I work (both run on my own transcripts, nobody else's): one reviews many sessions to identify commonly repeated instructions and amendments requested; the other analyses session logs to identify where the agent tends to require guidance or appears to struggle, within my various harnesses, that is, where the desired course of action is not sufficiently defined. So these both feed back to me how I could further improve my use of the agent, generally leading to new "flows" implemented as skills, tests and other hooks to be automatically invoked. There is no obvious relevance to any client.
So, the logical objection raised by Claude was that if successful this would cause more and more of my "flow" to be reflected in these files. Fair enough, and clearly an additional reason I should retain them! The ongoing process of improving them is clearly as valuable as the current state, and neither could profitably be handed over: handing over current files would be handing over many months of me correcting my own sessions; they would soon become obsolete without the ongoing improvement process continuing for my benefit alone.
Components of a typical harness
As discussed so far, it can appear as a more-or-less indivisible block to be passed to the client or not. In practice it consists of a wide range of items, some of which should and some should not be supplied to the client. So again, the relevant criterion is not so much "is it part of my method?", but "could their own agent readily determine this?". It also serves to show me that much more than I had realised is necessarily passed to the client!
| Layer | Handed to the client | Client's agent can rebuild it | Kept by the engineer |
|---|---|---|---|
| Delivered code, tests and migrations | Yes | N/A | No |
| Gates and checks compiled into the product | Yes | N/A | No, judgment that became product |
| Operating and explanatory documentation | Yes, facts and current state | Partial | No |
| Traps of their system found the hard way | Yes, written as state, no lesson | Yes, an agent infers the lesson | Partial, the lesson |
| Recovery procedures for their production | Partial, state yes, steps no | Yes, steps follow from the state | Partial, the steps |
| Method rules learned from incidents | No | No, they come from failures | Yes |
| Guards: production write gates, fail-closed hooks | No | Partial, generic versions exist | Yes |
| Skills, harness standard, self-improvement loop | No | Partial, public skills exist | Yes |
| Global instruction file and toolchain wrappers | No | Partial, part of mine is open source | Yes |
Firstly there will be a good deal of simple information concerning the client's various systems: server and directory locations and structure, cron jobs and contents, database tables, and so on. Assuming adequate access and the codebase this should all be readily determinable by their own agent, probably within a few hours. So there is no real point withholding it from them, and my friend's Claude made this point well. I would naturally expect to supply an appropriate amount of detail as to all systems and configuration relevant to running the software supplied ("sanitised" documentation).
As discussed, I can expect a good deal of my rules and practice to be reflected as tests, canaries (small checks that measure the data against its source) and similar in the delivered code; no reason why they should not be, and of course they will be expected as part of the supplied system. So my friend's Claude is correct that some of my method inevitably reaches the client, and this will continually reduce the amount which would be unique to me.
Various other items fall midway between these two extremes. For example, I would expect to be able to provide comprehensive instructions to restore the production environment if necessary: database corruption, bad update, and so on. The current state of all the relevant elements (location and nature of backups, and other running services) should of course be provided; but are the steps to follow also part of my method, or part of their system? I would consider them part of my method, and keep them. However, I would naturally include notes on any pitfalls discovered, such as staging and production DBs running on the same machine, or the firewall banning an offending IP address entirely, ssh included. But I would not state the implication, for example, avoid lengthy updates on staging during busy periods.
Claude made a good case that any competent engineer, and presumably any agent, would readily draw the obvious conclusions from such information, and so much more of my "lessons learned" would be passed to the client than might be obvious. I accept this argument, and will go on to explain why I am content to allow it.
Finally come the various rules discussed earlier, for example on sampling from an ordered population (the first thousand rows of a sorted table are a prefix, not a sample), testing against source data rather than current system data to avoid inheriting any systematic error, ensuring tests can detect errors. These would all be hard if not impossible to deduce from the systems involved, and represent lessons learned from errors. Also included would be various "trips" requiring my specific input (typically passphrase) for certain actions in production, set to time out after a short period, hooks refusing certain actions if unable to validate them, and other functions performed by but requiring final decision from me. I have set out much of this generally in an article describing a typical complete production harness (in Italian), which I consider sufficient for general publication.
So the record of decisions is clearly client information; however the means to record and interpret it so that an agent is directed to consult and obey it would seem properly mine to retain.
Ownership of documentation
As discussed, I would expect the client to be entitled to any information and documentation concerning their systems necessary to use the software supplied. In Italy, trade usage can make this part of the contract even where it is not written, as explained below. There is no suggestion that the full set of files used by my agent to generate that information would be included.
Initially I maintained that I was under no obligation even under general contract law to supply any documentation whatever, but would of course do so as a matter of fair dealing. As can be seen this is not strictly correct:
- Art 1374 Codice Civile binds parties to all consequences provided by law or, absent that, by custom or equity
- Art 1340 deems contractual terms commonly included in such contracts to be included unless it appears the parties did not want them
- One of the customs recorded in the Raccolta provinciale degli usi of the Province of Turin, 2000-2005 edition (the only collection I have verified; other provinces may record different customs), is that in software development contracts it is standard for the supplier to provide appropriate operating and other explanatory manuals, and to train the client's staff in their use
- See, for example, the guide to software development contracts issued by the Turin Chamber of Commerce, considering it self-evident enough to be omitted from the contract.
Note
I'm of course no lawyer, this is one source recording one Province's customs from some years ago, in relation to supply of new software, and can be excluded by the contract. I haven't researched to what extent this has been applied by the courts. In any event it is clear this would cover documentation as to operation of the software supplied only, not other notes concerning the supplier's methods.
So again it seems fair to conclude this covers appropriate documentation concerning the client's current systems and configuration, which I would expect already to provide in sanitised form as discussed. As it will normally be necessary to use the product supplied, it would seem it should be provided whether included expressly or not. I would naturally be happy to provide if requested or included. There seems no justification to include any other aspects of my instruction files. So again analogous to other tools and implements used by an artisan, and not part of what is delivered.
Replaceable after all
So it would seem, combining the previous sections, that another competent developer provided with the code, tests and other checks built into it, and all this information, would be able to adequately maintain the client's system using any coding agent (Claude, Codex, Gemini or whatever comes next). So I would be readily replaceable even without my current harness. Our discussion led me to acknowledge as much explicitly.
So what I am seeking to preserve is a significant margin of superior quality (the difference between a system that is merely maintained and one that is governed), from ensuring appropriate and adequate tests performed before any production change, identifying and addressing root causes rather than symptoms, all quoted figures appropriately qualified, and so on. So the various "trips" discussed will allow a substantially inferior engineer to safely continue with minimal risk of serious error: clearly these would be most undesirable to pass over, allowing a substantially cheaper provider to continue apparently satisfactorily for some time, until catastrophe struck!
Furthermore, as explained, I can expect the content of these files to change significantly month by month, while any static copy would of course remain as supplied at completion of the project. Even so, it is easy to imagine the client considering the quality difference insufficient to justify the cost difference, and choosing an alternative provider. This is an inevitable commercial risk, which can presumably only be addressed by continuing to deliver excellent results and a high level of customer loyalty. I have several clients in this position, able readily to provide equivalent equipment and resources, who nevertheless prefer to continue with me, presumably aware of what they can expect from my methods.
So who am I withholding these files from?
I assume there are a number of engineers who share many of my views, and would implement similar measures if given the chance. There are a few to whom I would gladly explain in detail how I work (and do), confident they would make similar use of the information. But in any event I would only discuss ideas, and not pass over any actual files. So in practice I retain the files from everyone, and the line runs between ideas and actual files, whoever the person.
So primarily I would be concerned about a cheaper alternative being provided with my files to continue with my client, either directly by the client, possibly with junior staff, or by competitors lacking equivalent skill but happy to adopt much of mine. As explained, I don't consider ideas alone a risk in any of these cases. Claude naturally suggested that they could readily use an agent to generate similar hooks, etc., given the general description published as referenced. Probably true to some extent, but only able to duplicate the form, without my feel for what to implement next, what to modify, when to add a more formal test, and so on.
So this leads me to be fairly liberal in publishing various aspects of my method, as indicated: general tooling published as OSS (gash, described earlier), general description of my production harness as linked, many articles such as this giving considerable further detail. All these convey only ideas. In contrast my actual instruction files, trips and other controls, skills, standard harness, and improvement tooling remain unpublished.
Matt Pocock
It was some time after I had developed these methods that I came across a video on the home repo pattern by Matt Pocock describing substantially equivalent measures: all his skills, other instructions, wiki and other special tools are contained in one "home" repository from which all others can be accessed (details provided in its agents.md). Perhaps unsurprisingly, I also have my home directory as a repository replicated to all machines (through git, to a private remote of my own), from which my various project-specific repositories are similarly accessed.
More interesting to me is that he also publishes a set of skills under MIT licence, described as taken directly from his own agent directory. However, in the video he refers to those in his home repository as skills he does "not want to release for whatever reason because they are extremely good and extremely sensitive to my business". Similarly his wiki is described as an enormous quantity of information sensitive to his business. So despite devoting much of his public activity to expounding these and similar methods he would appear equally unwilling to release at least some of his implementation details. So my friend's Claude would presumably have regarded the split as a marketing choice. I would prefer to regard what he keeps simply as what is rightfully his.
Avoiding leakage
Naturally I take great care to avoid these files being included in any client repository, though this is probably more an issue of constant attention than great security. All are held centrally in a private repository on each machine, symlinked to the current project, and excluded from the client repository. In addition I have a simple check excluding references in code comments to the ID of any relevant ticket.
# The harness lives in a private store; the client's repository only sees links it ignores
ln -s ~/store/projects/acme/.claude .claude
ln -s ~/store/projects/acme/AGENTS.md AGENTS.md
ln -s ~/store/projects/acme/CLAUDE.md CLAUDE.md
printf '%s\n' .claude AGENTS.md CLAUDE.md >> .git/info/exclude
# Delivered code names the rule, never the internal card that motivated it
if git grep -nE '\b(OPS|DEV|SUP)-[0-9]{2,3}\b' -- src/ tests/; then
echo "internal ticket IDs found in delivered code" >&2
exit 1
fiAfter substituting appropriate prefixes for those shown, you may wish to experiment with this in, for example, a regex tester, and check that it does detect some examples deliberately inserted! Any reference would be meaningless to another developer but would indicate existence of further information, while simply describing any rule concerned would be self-explanatory and reveal nothing additional. Also, instruction files of this kind can all be considered potentially vulnerable to malicious attack, as discussed in the article on treating AGENTS.md and instruction files as code (in Italian).
Naturally some clients will have their own set of files applicable to development by their staff, included in their repository. As described, my standard (I call this placement an overlay) allows these to be left as is and unmodified, with mine simply over-riding them during the period I am active, to be removed thereafter, and of course the harness will prohibit any commit and push during this time. So again no possibility of inadvertent inclusion of any of my files.
However, as discussed, some leakage can hardly be avoided. Apart from the obvious inclusion of some checks in delivered code: I will often install additional scripts, such as daily checks (one of them runs early every morning), directly in the client's environment; these will incorporate some of my methods and so reside outside my control. Perhaps most significantly, my professional instinct pushes me to advise the client not only to correct the specific problem reported but how best to avoid recurrence, and what other associated issues to anticipate. This would again reflect much of my general aptitude and approach. It is clear the client hasn't asked for, or paid for, any of this, and so every such unrequested explanation leaks a good deal of "engineering judgment" for free.
...and away he goes
Presumably there are many circumstances in which a business would wish to terminate the services of an employee, after which the only assets remaining to them would be work completed to date and any general information acquired. All their individual skill and knowledge would of course depart with them! It seems clear to me that passing over my complete set of instruction files, etc., would be analogous to leaving all this behind on the business's premises.
Naturally there are countervailing considerations: as discussed they are liable to be rapidly outdated with each new release of the underlying model. As recently as July 2026 Anthropic announced that it had eliminated over 80% of the system instructions for Claude Code with the arrival of Claude 5 models, recommending similar reduction to users' own instruction files and other skills, as many would now be inappropriate or conflicting (see the new rules of context engineering for Claude 5 models). So I would expect any snapshot of my current files would be noticeably out of date after a few months, and the recipient would be ill-equipped to evolve them appropriately.
However, presumably the most slowly changing elements would be the various "trips" and rules generated by actual errors and incidents, which are also those I would be most reluctant to part with. Further, it is notable that with the emergence of common standards such as AGENTS.md (one of the initial projects of the Agentic AI Foundation) and Agent Skills (recently transferred there by Anthropic, already in use by over 70 products, including ChatGPT, Cursor, GitHub Copilot, VS Code, and others) any such files passed over could readily be used with most other similar agents, possibly including those subsequently preferred by the client. So any copy passed over would serve whoever took my place just as well in their own tool: the format is open, but there is no corresponding obligation or advantage in making the content generally available!
Claude pressed me as to why I did not consider it equally important to prevent Anthropic acquiring this information, given that everything I provide as instruction and response will of course pass through their systems, and they do study how experts use the agent, as evidenced by the extensive analysis discussed earlier (400,000 sessions, in aggregate). I consider it significant that any such learning would be generalised into the basic model available to all users, the same movement that allowed their dramatic reduction of their own instructions. So they would never be likely to take over a specific client project using my own specific set of files, whereas a substitute holding them could; that is the risk in passing them over. So again I consider my continuing improvement at a significantly faster rate than they could incorporate in updates more than sufficient protection.
Would I sell?
The final suggestion from Claude was naturally whether there was a price at which I would be willing to pass over all my current files (not specially adapted) to a client. For two separate reasons I would consider this unacceptable.
As explained, I consider I am selling my skills and judgment by the hour throughout any engagement, to be applied to an unlimited variety of decisions and actions. So the client benefits throughout from all these, without acquiring any right or ownership of them themselves. It is clear that the various files are simply means of extending and applying my judgment in most areas, and I would no more expect to leave them behind for each engagement than expect a surgeon to abandon his instruments after each operation (still less inside the patient). If the object of the engagement is itself to acquire a set of flows to continue after my departure, this would of course warrant a specific project to develop appropriate files, and those files would naturally stay with the client on completion; they would be developed for that purpose, and would never be a copy of mine.
Inevitably there is also a strong element of personal attachment: these represent probably the most comprehensive expression I have ever achieved of much of my thought processes. It's difficult to imagine I would have considered parting with them had I been able to reduce them to files 20 years ago. So I continue to regard them very much as in the category of things whose benefit I am happy to rent out through my own work, but not to sell.
Still disagreeing
So I remain convinced I am correct, and my friend equally so! It is pleasant to have someone with whom to debate the appropriate division between deliverables to the client and other aspects of one's own skill and knowledge: until recently there could hardly have been any question, as the latter was necessarily intangible and untransferable. Now, at least much of it can readily be captured and passed over to be acted upon by another's agent. As discussed, I would be happy to pass over a wide range of information about their systems, much of which they would be entitled to expect anyway; but otherwise prefer to retain all means of continuing to apply and improve my methods. Others using agents to deliver work to clients will presumably have considered similar questions (if you have read this far, you probably have), and I would be interested to hear others' views on how far they go. Anyone with a specific requirement to use agents in developing software may wish to submit details via my free quote form, and I will happily advise whether this falls within my current experience and capability, and otherwise suggest others better placed.
