Press enter or click to view image in full size

AI Agent

Agentic Ai

Software Development

Teamwork

Best Practices

Personal AI Agents to Shared Team Knowledge : Making AI Coding a Team Practice

Arthur LIEGE

23 min read

·

22 hours ago

--

Listen

Share

AI coding agents are getting better at writing code, reviewing pull requests, and handling increasingly complex tasks. But while we’ve spent a lot of time improving what our agents can do, I’ve started wondering whether we’ve paid enough attention to how they fit into the teams we work with.

This article is a reflection on that question, and on how shared knowledge, team conventions, and composable skills might matter just as much as the tools themselves.

Table of contents

From tools to the team

1. We started with the tools
2. And somehow, it all works
3. When my code becomes our code
4. The agent adds another variable
5. A green PR isn’t necessarily an aligned PR

Sharing what the team knows

1. This is where skills get interesting
2. What my agent knows, yours might not
3. Share building blocks instead of building a God Agent
4. Not everything deserves a skill

Composing without centralizing everything

1. What belongs to the team, and what belongs to the product
2. Compose instead of piling things up
3. One rule, multiple consumers
4. When a Markdown file becomes a collective decision

Putting it into practice

1. Taking the experiment further
2. What I’d do on Monday morning
3. What if it works somewhere else?
4. Maybe the tool was never the real issue

1. We started with the tools

Over the past few years, AI tooling has gradually made its way into developers’ day-to-day work.

An agent here, automated review there, a new model, skills, MCPs, workflows, tools capable of taking on longer and longer tasks. You discover a topic, read a few articles, sometimes the entire documentation, sometimes just enough to use it properly, and then move on to the next thing.

Pretty quickly, it all starts working.

That’s the part that started bothering me a little.

Whenever we talk about introducing a new tool into a team or a product, I usually argue for the opposite approach: start with the problem.

• What is costing us time?
• What is frustrating us?
• What would we actually like to improve?

Only then do we look at the available solutions and ask whether AI has anything useful to bring to the table.

And yet, with my own development tools, that’s not really what I did.

Like a lot of developers, I mostly went with the momentum.

2. And somehow, it all works

I started by using Codex in the cloud on my repository. Then I installed Codex Desktop on Windows while still using Codex Cloud from Linux.

Later, when agentic coding really started taking off, I installed OpenCode and connected whatever enterprise AI provider I had at the time, along with my personal provider.

And the days just kept going from there. Somehow, it all kept working.

I’d ask for a feature, let the agent work, correct a few things, run it again, ask for changes, review the result, and eventually the code would land in the codebase.

Did that sequence of choices lead me to the right tools? Probably.

Am I using them the right way? Mostly.

Optimally? I honestly have no idea.

The problem isn’t that Codex, OpenCode, or the other tools don’t work. Quite the opposite: taken individually, my workflow works pretty well.

The questions start when you stop looking only at your own workstation.

3. When my code becomes our code

Being a developer usually means being a developer on a team.

The final codebase is a patchwork of everyone’s work.

Before agentic coding, each developer was responsible for their own code and tried, as best they could, to stay close to the team’s habits: its quality bar, the way it split components, files, and responsibilities, the abstractions it preferred, and so on.

There was a kind of implicit, partly intentional consistency that helped everyone find their way around each other’s code.

A team’s rules are never captured in one exhaustive, perfectly maintained, versioned list somewhere. And thankfully, they’re not set in stone either.

A way of doing things can work perfectly well for months simply because the project has never needed anything else. Then a feature comes along, exposes a limitation, and the team gradually adapts the architecture.

On one backend I worked on, for example, we originally had very few listeners. They all lived in a single file, and there was no real reason to do anything differently.

Then a much more complex payment feature arrived. The number of listeners grew, their responsibilities changed, and keeping everything in the same file stopped making much sense.

So that file was split into several domain-based subfolders, still under the same listeners directory.

That wasn’t a rule defined when the project started.

Nobody had written six months earlier:

Once we reach X listeners, we must create domain-based subfolders.

That way of organizing things emerged because a real feature forced us to reconsider the structure we already had.

From that point on, it naturally became a new reference for the team. The next developer adding a listener would probably look at what already existed, a colleague could explain why the structure was organized that way, and a code review could ask someone to move a file if they put it in the wrong place.

That’s also how part of a team’s technical culture gets built: through accumulated decisions, corrections, and precedents.

Some of those decisions make it into documentation. Some become lint rules or tests. Others remain visible in the code, or simply live in the heads of the people working on it.

It wasn’t perfect before AI either. Two developers could obviously still have different styles. But part of the repository’s consistency was transmitted simply by working together, reading each other’s code, and adjusting things through code review.

So some of what kept our code consistent wasn’t in the toolchain at all.

It was in the developers.

4. The agent adds another variable

Is that still true with agentic coding? To some extent, yes but the equation has changed.

When some PRs can contain 20, 50, or 200 changes, I wouldn’t be very confident saying that everything being produced necessarily matches the team’s habits and expectations.

Especially because the output no longer depends only on the developer.

It can depend on:

• the provider;
• the model;
• the reasoning level;
• global instructions;
• the available skills;
• connected tools;
• the context that was loaded;
• how the developer prompts;
• how many iterations happened;
• what was corrected afterwards.

Of course, an AI can read the repository. It can inspect what already exists, read the documentation for the technology in use, and try to reproduce the patterns it sees.

I do something similar when I build a feature: I spend time understanding the codebase, read documentation, and look at example repositories when needed.

So the difference isn’t simply:

The human understands the project and the AI doesn’t.

That would be far too simplistic.

But two developers can now work on the same team, in the same repository, on the same tickets, with the same CI checks, while giving their agents very different contexts and instructions.

Team variability just gained another dimension.

5. A green PR isn’t necessarily an aligned PR

But Arthur, the code passed all the unit tests, all the checks, even our AI reviewer only raised two tiny warnings that were easy to fix!

That’s true. But does the code actually match the way the team wants to work?

Let’s take a deliberately simple example. Imagine a React team has a convention that a file should never contain two UI components. That’s neither a React rule nor a TypeScript error: the code can compile, the tests can pass, and both components can work perfectly well. A generic AI reviewer may quite reasonably see nothing wrong with it.

And yet, for that team, the code is not organized the way it should be.

A green CI pipeline answers some questions very well, but it does not automatically answer this one: is this the code this team wants to produce?

At this point, we could conclude that we simply need a better AI reviewer, a more powerful model, or more context. But I think that mixes up two different problems.

The first is code quality: does it work, handle errors correctly, avoid regressions and unnecessary complexity, use APIs correctly? Better models, better tools, better tests, and more context can absolutely help with all of that.

The second is alignment with the team’s conventions. Our two-components-in-one-file example raises exactly that question. The code can be perfectly valid, even very good, while still violating a convention that belongs specifically to the team.

A model can know React extremely well without automatically knowing that, in our team, we consistently prefer one UI component per file. It can inspect the existing code and try to infer that convention, but only if the convention is visible and consistent enough in the first place.

And more importantly: why ask the model to rediscover it every time if we already know the rule exists?

I see three fairly different categories here.

The first is everything we can verify deterministically: the compiler, TypeScript, ESLint, tests, CI checks.

The second is the model’s general knowledge: React, TypeScript, common patterns, common mistakes, well-known best practices.

The third is everything that actually belongs to our context: why this architecture is organized the way it is, why we use this utility instead of another one, why one convention exists even though another solution would be perfectly valid, how our team wants reviews to be done, or how we want a feature to be prepared before implementation begins.

Up to this point, I had mostly been trying to make my agents better.

But if what I really want is for them to work more like our team, then the problem isn’t just how smart they are.

They also need access to some of what the team already knows.

6. This is where skills get interesting

This is where skills start to become interesting.

If you already use Codex, Claude Code, or another agentic coding environment, you’ve probably come across them or installed a few already.

I’m not going to reintroduce the whole concept here.

The part that matters for this article is fairly simple: a skill packages instructions, a method, and sometimes additional resources so an agent can use them when they become relevant to the task at hand.

If you want a quick refresher before continuing, the Agent Skills specification is a good place to start: Agent Skills

There are already a huge number of skills out there:

• general-purpose ones;
• skills for specific technologies like React;
• review skills;
• planning skills;
• much more specialized or completely niche ones.

I’ve installed, selected, removed, and modified plenty of them myself.

And yes, they can have a major impact on how an agent works.

Except that, at this point, I’ve mostly solved a personal problem: my agent works better, on my machine.

7. What my agent knows, yours might not

But has that become a genuinely shared practice across your team?

Do you use the same skills as your colleagues, at the same versions and for the same purposes? Do you actually know what is guiding the agent used by the person who just opened a PR?

This is where things become much fuzzier on the projects I’ve worked on recently.

I have my skills on my machine. Some more generic skills are sometimes versioned with the project, for example in a .agents directory. But I rarely have a precise view of what is installed or configured on my colleagues' machines, let alone where those skills came from or which versions they are using.

So we can use the same AI, the same model, and work in the same repository while still giving our agents different rules and different context.

Let’s go back to our React convention:

A file never contains more than one UI component.

Case 1: only the developer knows the rule

My agent knows the convention and applies it whenever it generates a feature. It will naturally split the components into separate files.

Great for me.

But if another developer doesn’t have that rule and opens a PR with two components in the same file, our automated review agent doesn’t know about it either. As far as it’s concerned, there is nothing special to flag.

The convention exists, but only on my machine.

Case 2: only the automated reviewer knows the rule

Now take the opposite situation: the convention exists in our review agent’s instructions, but not in my local agent’s instructions.

My local agent can generate something like this:

Feature.tsx
  Feature
  FeatureButton

I push the PR, and the review agent replies:

Two UI components in this file. Please split them.

So I go back to my local agent, ask it to make the change, then push a new version.

It works.

But we’ve just built a fairly absurd loop:

generate
→ push
→ detect an already-known convention
→ fix
→ push again

The rule was available before the code was even produced. It just wasn’t available in the right place.

Case 3: the knowledge is shared

In the third case, both the local agent and the review agent know the convention.

The first can apply it during generation. The second can verify that it was respected during review.

They don’t have the same role, and they don’t need exactly the same instructions. But for this specific rule, they share the same knowledge.

And that’s where the interesting question appears:

Why maintain the same convention separately in multiple tools that all contribute to the same product?

8. Share building blocks instead of building a God Agent

Maybe the goal isn’t to standardize our agents after all, but to standardize some of the knowledge they need to share.

The question is how to organize that.

That’s when I started looking more seriously at the idea of composable skills. We already have plenty of “composable something” in software: composable infrastructure, composable architecture, composable UI… People in tech clearly love the word.

I do too.

One useful line of thought comes from Skillsmith’s Agent Skill Framework. What I take from it isn’t necessarily their exact split between agents, skills, and subagents, but a broader principle: one responsibility shouldn’t automatically carry every piece of context and every capability available to the system.

If we keep accumulating instructions, knowledge, and behaviors in one place, it’s easy to end up with a “God Agent” that is supposed to know everything and do everything. But the opposite extreme exists too: splitting every tiny instruction into its own capability doesn’t automatically make the system more modular. It can just make it much harder to understand and maintain.

Another article that resonated with me is Mario Giancini’s piece on Composable Skills. This time, the part I care most about is duplication.

If the same capability or rule is described in several places, those copies can gradually drift apart.

Back to our example. I could write this in the instructions for my implementation agent:

Never put two UI components in the same file.

Then copy the exact same sentence into my review agent’s instructions.

That would work.

But I would now have two sources of truth for a single convention. The day the team decides to change it, we have to remember to update both. And if a third workflow needs the same rule tomorrow, we’ll probably create a third copy.

Composition suggests another way to think about it.

My implementation agent and my review agent do not need to be identical. They don’t even need to share all their instructions. They simply need to be able to rely on the same building block wherever their responsibilities overlap.

So the goal isn’t to build one enormous:

THE-ULTIMATE-COMPANY-AGENT.md

that knows our entire product, every technology we use, every convention, every working method, and every tool.

It’s to identify a few sufficiently focused building blocks with clear responsibilities, then reuse them only where they are actually relevant.

9. Not everything deserves a skill

Once you start thinking in terms of skills, it’s very easy to want one for everything.

A skill for writing React, another for code review, another for naming variables, another for creating hooks, and obviously one to remind everyone that useEffect is not the answer to every problem.

And eventually, why not a skill whose job is to tell the first skill when it should call the third one.

Give it a few weeks and we can probably recreate a small company inside Claude Code.

That’s obviously not the goal.

Mario Giancini raises an interesting question here: as models improve, do we really want to keep adding scaffolding around things they already know how to do well?

I don’t think the answer is simply:

The model already knows how to do it, so no skill is needed.

A good model already knows how to perform a code review. But a team may still want to stabilize how it does that review: understand the scope first, distinguish facts from assumptions, separate requirement compliance from implementation quality, prioritize findings, and make explicit what could not be verified.

So the better question becomes less:

Does the model already know how to do this?

and more:

Do we have something specific, recurring, or important enough that we want to stabilize it?

And even then, “skill” isn’t necessarily the first answer.

If TypeScript can guarantee a constraint, I’d rather let TypeScript guarantee it. If ESLint can detect something unambiguously, I’d rather write an ESLint rule. If a test can prove a behavior, I’d rather write a test.

I have no interest in asking a probabilistic model to verify something a deterministic tool can already guarantee on every build.

The same caution applies to generic knowledge. An internal fifty-page skill that re-explains the basics of React would probably have little value: we’d have to maintain it, it could become stale, and it could eventually conflict with newer documentation or with the model’s own more up-to-date knowledge.

The interesting part starts when we’re trying to stabilize something genuinely local or methodological.

For example:

On this team, a review always starts by checking the requested behavior before suggesting refactors.

Or:

In this product, calls to this vendor always go through our internal adapter, even though its SDK can be used directly.

Or:

For a complex change, we start with a plan organized around outcomes and dependencies rather than a simple list of files to modify.

Those aren’t just programming facts. They’re ways of working, architecture decisions, local contracts, or methods we want to carry from one task to the next.

Skills don’t replace the compiler, linters, or tests. Nor should they become an encyclopedia of everything the model already knows.

They can instead occupy the space that’s left: the things we want to make explicit, reusable, and stable enough for several agents to rely on.

10. What belongs to the team, and what belongs to the product

So what can I actually put in place within a team to make reviews easier and make our agents more consistent in how they work?

A fairly natural first split is to distinguish between the team’s way of working and knowledge that belongs specifically to the product.

A team skills repository

I’d start with a repository owned by the team. Not one giant catalog shared across the whole company: just a place to version the handful of working methods we genuinely want to share.

For example, it could contain a planning skill. It wouldn't know our application or our architecture. Its job would be to describe how we want to go from a sufficiently defined objective to a plan: identify dependencies, risks, and checkpoints, then produce verifiable units of work instead of a simple list of files to change.

A review skill could formalize how we want to review a change: understand the scope before judging the implementation, distinguish a real problem from a preference, ground comments in verifiable evidence, and prioritize findings.

Likewise, a debugging skill could state that we first want to reproduce the problem or build a sufficiently reliable signal, test several hypotheses, then confirm the cause before rushing into a fix.

Maybe the team only needs two of those skills. That’s fine. The goal isn’t to fill a repository; it’s to identify the working methods that genuinely benefit from being shared and stabilized.

Product-specific skills

Alongside that shared foundation, some knowledge belongs directly to the product and has no reason to follow us into every other project.

For example:

• payment-domain, to document payment invariants, boundaries around our PSP, or operations that need to be idempotent;
• project-react-conventions, to capture frontend-specific decisions: component organization, design system usage, forms, or state management;
• project-architecture, to make module boundaries explicit and document dependencies the team deliberately chooses not to introduce;
• or something much more focused like listeners-architecture, explaining why our listeners are now organized by domain and how the next one should be added.

That knowledge can stay directly in the product repository, in a .agents directory or somewhere else depending on the tools and conventions in use.

The exact folder name matters much less than ownership: who owns this knowledge, and in what context should it evolve?

What belongs to the product stays with the product.

What describes a shared way of working for the team can live independently and be reused from one project to another.

11. Compose instead of piling things up

From there, we can stop asking only:

What agent should we create?

and start asking a different question:

What capabilities does this task actually need?

A feature implementation might combine:

planning
+ implementation
+ react
+ project-conventions

A review might use:

review
+ react
+ react-review
+ project-conventions

And a bug investigation:

debugging
+ react
+ project-conventions

Why not simply give every agent the same skills? Because their roles are different.

Take review and implementation. An implementation agent needs to inspect the existing code, understand the scope of the change, modify the repository, and validate the result. A review agent works on the same code, but with a different responsibility: its job isn't to silently fix what it sees, but to analyze a given state, identify issues, assess their importance, and provide enough evidence for someone to decide what happens next.

If those responsibilities get mixed together, the boundaries become blurry very quickly. The reviewer can start changing things it was supposed to analyze, while the implementation agent can spend its time producing a full review report instead of finishing the requested change.

The same principle applies to debugging. Diagnosing a problem first means narrowing the hypothesis space and establishing a likely or demonstrated cause. Once that cause is identified, an implementation capability may be needed to apply the fix. A single task can therefore use both without turning them into one responsibility.

The separation also applies across technology layers. review has no reason to contain every React rule; react-review doesn't need to redefine the entire review methodology; project-conventions doesn't need to explain how to debug or review a change.

Each one contributes a different layer.

Composition doesn’t mean every agent eventually receives the same skills. Quite the opposite: it lets us give each one only the capabilities it needs while reusing exactly the same building blocks wherever responsibilities overlap.

12. One rule, multiple consumers

Let’s use our example one last time:

One file = one UI component.

The developer’s agent could rely on:

react
+ project-react-conventions

while the automated review agent might use:

review
+ react
+ project-react-conventions

The project-react-conventions skill doesn't need to know the full logic of a review or how to implement an entire feature. It simply contains product knowledge that happens to matter in both contexts.

That convention doesn’t belong to Codex, Claude, or our review tool.

It belongs to the project.

From there, the CI/CD pipeline becomes much more interesting. The automated review tool is no longer another AI that needs a separate explanation of part of the project’s culture; it becomes another consumer of some shared knowledge.

Not all of it, obviously. The reviewer still has its own responsibilities and its own context. But when a convention affects both what should be produced and what should be checked, there is no reason to maintain two separate sources of truth.

That also means the people maintaining the automation need to be part of the conversation. Not because they should debate every wording change in every skill, but because a rule used during both generation and review is no longer just one developer’s local preference.

It becomes a product rule.

13. When a Markdown file becomes a collective decision

This is where things start getting interesting.

A skill can begin as a simple Markdown file on one machine. But once several developers, or even a CI pipeline, depend on that same file, changing it is no longer entirely an individual decision.

If I change our review skill tomorrow so that a certain category of issue becomes blocking, I'm no longer just changing my personal prompt. I'm potentially changing the way the entire team reviews PRs.

So we need at least a little governance.

And, as with every good governance topic, we could obviously start by scheduling a meeting. Then a meeting to prepare for the meeting. Then, with enough ambition, a monthly committee to oversee the whole thing.

Or we could remember that we’re still mostly talking about text files versioned in Git.

Someone wants to change a rule? They open a PR, explain why, the relevant people review it, and we merge if the change makes sense.

Git already gives us most of what we need:

• a diff;
• an author;
• a history;
• a discussion;
• the ability to roll back.

For a team that’s just getting started, that’s probably enough.

Governance can grow with the number of consumers. It doesn’t need to exist before they do.

If ten teams eventually depend on a catalog of hundreds of skills, new problems will naturally appear: versioning, ownership, compatibility, distribution, lifecycle. But there is no reason to solve those problems before we’ve even established that a few shared files provide real value.

And above all, a shared skill should remain easy to challenge.

If it adds noise, produces absurd behavior, or is barely used, we change it or remove it.

The goal isn’t to accumulate skills.

The goal is to reduce real friction in the team’s work.

14. Taking the experiment further

I wanted to push this logic a little further on my own. That’s what eventually led me to build Thisisjuke/skills, not as a repository every team should adopt, but as a playground for one question:

How far can we split capabilities into responsibilities that are clear enough to remain understandable and composable?

The repository isn’t designed as one large collection of independent prompts. For each skill, I try to answer three questions instead:

What responsibility does it own?
What does it deliberately not own?
What can it be composed with?

That separation already shows up in the top-level categories.

First, there are fairly general foundations:

foundations/
  planning/
  implementation/
  testing/
  debugging/
  review/

Then more specialized workflows:

common/
  api-design/
  domain-modeling/
  refactoring/
  research/
  ...

And then technologies and their own specializations. Around React, for example:

technologies/
  react/
    react-review/
    react-testing/
    react-performance/
    ...

The interesting part of this structure isn’t that the folders are neatly organized. It’s that the tree makes responsibility boundaries visible.

review can define a general review method without pretending to know every framework. react can bring React-specific knowledge and constraints without redefining the entire review method. react-review can focus on the issues and patterns specific to reviewing React code without copying everything already covered by review.

That lets us compose something like:

review
+ react
+ react-review
+ accessibility

Each building block is there for a different reason, and each one can evolve without forcing the others to gradually become partial copies of it.

This split also forced me to think about less obvious boundaries.

debugging, for example, does not automatically imply permission to modify the code. Its first job is to build a reliable signal, narrow the hypothesis space, and identify a cause. Once that cause is established, an implementation capability can take over if a fix has actually been requested.

Likewise, refactoring isn't just implementation with the word “refactor” added to the prompt. Its responsibility is to change the structure while deliberately preserving observable behavior.

And planning isn't there to rewrite the specification or make product decisions on the team's behalf. It starts from a sufficiently defined objective and tries to organize it into coherent, dependent, verifiable steps.

That’s the part of the repository that matters most to me in the context of this article.

Not the number of skills. Not their exact names. Not the directory tree itself.

What matters is that building these blocks forced me to make explicit boundaries I would otherwise have mixed together in one large agent prompt.

The repository pushes the experiment a little further around validation and distribution: the skills are checked, and a reproducible public version is generated from my working environment. That’s mostly plumbing around the experiment, and I’ve documented that part in HOW-ITS-MADE.md for anyone interested.

But you probably don’t need any of that.

And more importantly, that’s absolutely not where I would start with a team.

15. What I’d do on Monday morning

If I joined a team tomorrow that had never structured anything around skills, I’d start much smaller.

First, I’d create a repository shared by the team, with only a few genuinely cross-project skills. Maybe three, not thirty:

planning
review
debugging

Then I’d keep everything that depends directly on the product’s context inside the product repository:

.agents/
  react-conventions/
  architecture/

From there, I wouldn’t try to document every team habit immediately. I’d start with one convention the team already repeats regularly: something we often explain in review, a correction our agents repeatedly need after generation, or an important architecture decision that isn’t clearly represented anywhere.

Then I’d try to make that knowledge explicit once.

If it matters in several places, those different consumers should be able to rely on it. If react-conventions matters both to the agent generating code and to the agent reviewing PRs, both should be able to consume the same source instead of maintaining two variants.

The first version can be deliberately boring.

No registry, no internal platform, no automatic synchronization across fifteen tools. Take a few conventions the team already comes back to, make them explicit, then wire them into the places where they actually help.

Then observe.

Are there fewer repetitive review comments? Fewer corrections after generation? Fewer explanations repeated to every agent? More consistency between developers? A clearer understanding of what is actually guiding our tools?

If not, adjust.

Or stop.

The point of that first version isn’t to build a new internal platform. It’s simply to find out whether one shared source actually reduces friction the team was already experiencing.

16. What if it works somewhere else?

If this approach is used for a while and genuinely helps one team, then the question of sharing becomes much more interesting.

Imagine our repository has contained these skills for a few months:

planning
review
debugging

Another team comes across it, looks at our planning skill, and thinks:

That’s pretty close to how we work too.

At that point, there are several possible paths. They can simply take inspiration from it, create a version adapted to their own context, or use ours directly.

There is still no reason to centralize anything.

But if, over time, we realize that both teams are solving the same problem with sufficiently similar practices and are starting to pay the cost of maintaining nearly the same knowledge twice, the situation changes.

We’re no longer looking at a theoretical desire for standardization.

We’re starting to see real convergence.

Not:

We’re in the same company, so we obviously need one shared planning skill.

But rather:

We independently tried to solve the same problem in similar enough ways that maintaining two separate versions is starting to make less sense.

At that point, extracting that building block into a more shared space can become a pragmatic answer:

company-skills/
  planning/
  review/

team-a-skills/
  ...team-b-skills/
  ...product-a/
  .agents/product-b/
  .agents/

What matters most to me is the direction in which that sharing emerges.

I prefer:

local use
↓
validated by one team
↓
similar need in another team
↓
genuinely compatible practices
↓
duplication starts to cost us
↓
share it

over:

create the company standard
↓
ask teams to adopt it

In the first case, we already know why the building block exists, who uses it, and what it actually improves. We have real feedback, and we can start separating what is truly shared from what should remain specific to each team.

Most importantly, we’re not trying to architect a problem before we’ve actually encountered it.

That’s also the point where sharing the approach with other teams feels much healthier to me.

Instead of walking in with:

This is how you should work with your agents from now on.

we can simply share what actually happened:

Here’s the problem we had.
Here’s what we tried.
Here’s what we’re using today.
Here’s what is genuinely helping us.
Here’s what still isn’t working very well.

And if part of it is useful to you, have a look at how we built it.

If another team only takes our approach to planning, great. If they decide none of it fits their context, that’s fine too.

But if several teams naturally end up using the same building block, then we’ve probably found something that genuinely extends beyond the context of one team.

At that point, an internal meetup, shared documentation, or even an external talk becomes much more valuable.

Because we’re no longer presenting a theoretical architecture.

We’re sharing what actually worked in practice.

17. Maybe the tool was never the real issue

At the beginning, my question was mostly whether I was using all these new development tools correctly.

With a little distance, I don’t think that was really the right question.

Codex, Claude, OpenCode, or whatever I install next can all change. Models will change, interfaces will change, and a good part of what feels essential today will probably be replaced within a few months.

What interests me more is everything around them that doesn’t change quite as quickly.

A team already has habits, architecture decisions, review methods, ways of planning, ways of debugging. Some of that is written down, some is visible in the code, and a lot of it is still passed directly from developer to developer.

Once agents start participating in code production too, that knowledge needs a way to reach them.

Not all of it.

Not through one enormous company prompt.

And certainly not by turning every habit into a skill.

But when something is important enough to keep repeating, local enough that it can’t reliably be inferred every time, and shared enough to matter to several tools or several people, it’s probably worth asking where that knowledge should live.

That’s ultimately what I take away from all of this.

I’m less interested in building the perfect agent than in avoiding a world where every one of our agents has to rediscover, on its own, what the team already knows.

And if a few well-placed Markdown files are enough to start solving that, that’s probably already a pretty good place to start.

A small personal note

I didn’t start thinking about any of this because I wanted to design better agent architecture. I just wanted my own tools to work a little better.

But the more I experimented, the more the question became: how could I make this useful enough that my colleagues would actually want to take a look too?

I’m still figuring that part out, and that’s probably what interests me most now.