Why AI-assisted development requires a clear boundary between product code and developer operating systems.
Join developers getting comprehensive guides, code examples, optimization tips, and time-saving prompts to accelerate their development workflow.
No spam. Unsubscribe anytime.
For a long time, I treated the repository as the natural home for almost everything related to a project.
Application code went there.
Tests went there.
Architecture notes went there.
Implementation decisions went there.
Then AI-assisted development added another category of files:
I put many of those things in the same repository too.
At first, that felt like good engineering.
Everything was close to the code. The context was available to the tools that needed it. I could open a project and immediately have a development environment that understood the architecture, conventions, important decisions, and patterns I wanted to follow.
It worked extremely well.
It also took me a while to realize that I had mixed two very different things together.
The first was the product I was building for the client.
The second was the system I use to build products.
Those are not necessarily the same deliverable.
A developer used to arrive at a project mostly carrying knowledge in their head.
They knew how they liked to structure applications, how they debugged problems, how they reviewed code, how they reasoned about architecture, and which shortcuts were dangerous.
Some of that knowledge might eventually appear in documentation.
Most of it disappeared when the developer left.
AI-assisted development changes this.
A surprising amount of that working knowledge can now be encoded directly into the development environment.
An agent skill might explain how a particular class of components should be implemented.
A project instruction file might tell an AI assistant how the architecture is structured, which abstractions are canonical, what should never be duplicated, and where important boundaries exist.
An internal audit might document hundreds of observations about a codebase.
A workflow might coordinate multiple agents to inspect, implement, verify, and document a change.
A prompt might contain the result of months of experimentation around how to reliably perform a particular engineering task.
Individually, these files can look insignificant.
Collectively, they become something much more valuable.
They become a development system.
And that development system can materially affect how quickly and reliably someone can work.
Suppose I am hired to build a complex application.
The client should obviously receive the application.
They should receive the code required to operate it.
They should receive the tests that verify it.
They should receive the infrastructure and configuration required to run it.
They should receive the documentation necessary to understand and maintain the system.
They should not be dependent on me having some secret knowledge that makes the application impossible to operate after I leave.
That part has not changed.
But imagine that next to the application I also maintain:
.agents/
.claude/
internal-reports/
research/
working-notes/
private-automation/
agent-skills/
Those directories might contain reusable methods that I use across many projects.
They may explain how I perform architecture reviews.
They may contain generic debugging workflows.
They may encode how I use agents to refactor repositories, inspect migrations, analyze schemas, or validate implementations.
They may contain working material that was never intended to be part of the final system.
Putting all of that into the client's repository creates an accidental ownership boundary.
The distinction between documentation about the product and the machinery used to produce the product disappears.
The wrong lesson would be:
Never document anything because the client might learn too much.
That would be terrible engineering.
The client should not be trapped.
If an application relies on a complicated content model, document it.
If there are important architectural decisions, record them.
If deployment has unusual requirements, explain them.
If another developer needs to understand how a subsystem works in order to safely change it, that knowledge belongs with the system.
But there is another category of material that deserves a different home.
I now think about the split roughly like this.
This belongs with the project:
This may belong with the developer or delivery organization:
There will always be grey areas.
That is fine.
The important thing is making the distinction deliberately rather than discovering it accidentally six months into a project.
This became much more obvious to me when thinking about handover.
Imagine another development team takes over an application.
They should absolutely be able to understand the application.
But should they automatically inherit every tool, workflow, prompt, skill, internal report, and automation system I developed to make myself more effective?
That is a different question.
If those assets are part of the agreed engagement, of course.
If I was explicitly hired to build an internal engineering system for the organization, of course.
But if I developed them as part of my own working environment, their presence in the same Git repository does not automatically mean they were intended as part of the product.
This is very similar to other professional services.
A designer delivers the design.
They do not necessarily transfer every reusable template, research framework, reference library, or internal process they have developed over their career.
A consultancy delivers its analysis and recommendations.
It does not automatically transfer the complete internal methodology it uses to produce them.
Software development is beginning to look more like this because the development environment itself is becoming much richer.
The practical solution is not particularly complicated.
I now prefer thinking in terms of two repositories.
The client repository contains the actual product:
client-project/
├── application/
├── tests/
├── infrastructure/
├── migrations/
└── project-documentation/
My private development workspace can contain things such as:
private-workspace/
├── agent-skills/
├── prompts/
├── internal-reports/
├── working-docs/
├── research/
└── automation/
Locally, those directories can still be exposed inside the normal development workspace.
Symlinks, local configuration, workspace tooling, or other development-environment mechanisms can make them available exactly where Claude, Codex, editors, or local scripts expect to find them.
The developer experience does not have to suffer.
What changes is the ownership boundary.
A commit to the application goes to the client repository.
A change to an internal agent skill goes to my private development repository.
That separation turns out to be useful even when there is no commercial tension whatsoever.
It keeps client repositories cleaner.
It makes handovers easier.
It makes reusable tooling genuinely reusable.
It prevents internal experiments from becoming accidental project dependencies.
And it forces me to decide what documentation another developer genuinely needs.
There is another lesson underneath this.
When a client relationship is going well, it is very easy to operate informally.
You keep moving because you do not want paperwork to block progress.
You share context freely.
You put your tools close to the work.
You assume the next phase will happen because everyone says the next phase will happen.
Most of the time, that may be completely fine.
But commercial boundaries are most useful before there is a disagreement, not after one appears.
A clearly separated development system is not an expression of distrust.
Neither is waiting for a milestone to be authorized before starting a large amount of work.
Neither is deciding which assets belong to the client and which belong to your own operating system.
These are simply controls.
Good relationships and good controls are not opposites.
In fact, good controls often protect the relationship because fewer assumptions need to be renegotiated later.
There is also an important counterpoint.
I do not think developers should build their advantage around hiding information.
If your entire value disappears because another developer can read your instructions, there is not much defensibility there.
The interesting advantage is that the development system keeps evolving.
An agent skill is not valuable simply because someone cannot see it.
It is valuable because it captures experience, improves over time, connects to other workflows, and helps produce better decisions faster.
Someone may have a snapshot.
You still have the system that continues to evolve.
That distinction matters.
The objective is not secrecy.
It is ownership.
AI-assisted development is slowly changing what exists around a codebase.
There used to be an application and some documentation.
Now there can also be a substantial machine-readable layer explaining how the application should be reasoned about, extended, tested, reviewed, and changed.
That layer can contain real intellectual capital.
We are going to need better norms around it.
Some of it clearly belongs to the client.
Some of it clearly belongs to the developer.
Some of it will need to be explicitly negotiated.
But treating everything inside a working directory as automatically belonging to the same commercial category is becoming increasingly difficult to defend.
The lesson I am taking forward is simple:
The client should receive a system they can genuinely operate without me.
But that does not necessarily mean they need the entire system I use to make myself effective while building it.
The code is the deliverable.
The documentation required to understand and operate it is part of the deliverable.
The evolving development system behind it might not be.