Agentic development can make an engineer more productive while making their decisions harder for colleagues to see. I am concerned about what happens when the explanation stays in the agent session and colleagues only see the code.
Listening to Carlos Kelkboom on Beyond Coding led me to reflect on how agentic software development is changing communication within engineering teams. His observations about developers working with agents instead of colleagues, and the difficulty of agreeing on a shared vocabulary, stayed with me. I wanted to take those concerns into the everyday work of an engineering team.
Consider a hypothetical example. Two experienced engineers work on the same service in the same week. One adds a cache for customer settings. The other adds a cache for account configuration. Each works through the design with an agent. Another agent reviews the implementation against its specification. Tests pass, and both pull requests get approved.
The two names refer to the same data. Now there are two caches with different refresh rules. A month later, someone investigating stale settings asks why an update clears one cache but leaves the other untouched.
Neither engineer needed help writing a cache. They needed to discover that they were making the same architectural decision.
The reasoning moves into private sessions
An agent is available immediately. It can explain unfamiliar code, question a design, suggest alternatives, and check a change. I understand why this becomes the default. Asking a colleague means interrupting them or waiting for a reply.
That question also tells the colleague what I am changing. They might remember another engineer working on the same problem, or a production failure that never reached the documentation. When they explain why an earlier approach failed, I learn something I can use in my next decision.
When I take the question to an agent, my colleague may never hear about the change. Hearing who answers a difficult question also tells me who to ask later. A senior engineer entering an unfamiliar domain needs those conversations as much as anyone else.
In Code is cheap. Confidence is not., I wrote about reviewing intent and constraints before implementation. There is a communication reason too. A colleague can question a short plan before an agent builds around an assumption the team never discussed.
I would look for repeated surprises, such as someone discovering a decision after merge or two engineers building similar solutions. In a retrospective, ask who besides the author can explain a recent change. A quiet pull request alone says little about whether people understand it.
The following are a few practices we use in our team. Other approaches can help too, depending on how a team works.
Agree on the domain language
In the cache example, “customer settings” and “account configuration” sound like different concerns. Even “customer” might mean a person to one engineer and a billable organisation to another.
Start with a small docs/domain/glossary.md. Agree on the terms with the people who know the domain, including examples where a definition leaves room for interpretation:
| |
The complete example glossary also defines the freshness window and the shared settings cache. All these rules are hypothetical. A real team needs to establish its own definitions.
Knowing that both names mean the same data gives the second engineer a reason to look for an existing provider. Link the glossary from the repository’s agent instructions and ask the agent to read it before planning. Update it when a discussion changes a definition. The team still needs to check the implementation against those definitions.
Meet to write the specification together
For work across component boundaries, gather the affected engineers before they begin separate agent sessions. Include whoever knows the production history or business rules. For a first session, try thirty minutes on one feature.
Write in one shared document. Someone can type, an agent can draft while everyone watches, or the team can validate an existing specification. In the cache example, the request handler and scheduled worker both read the settings. Agree on how long stale data is acceptable and what each caller does during failures:
| |
The example specification includes operational checks and open questions. An agent can suggest missing cases. The team needs to confirm that five minutes meets users’ needs and that the database can handle traffic when the cache fails.
The discussion gives the second engineer a chance to say they were about to build the same thing. Assign someone to answer any unresolved question. I expect catching overlapping plans here to cost less than combining two finished implementations, but that is an expectation to test.
Record the architecture colleagues will implement
The specification describes the behaviour. An architecture decision record, or ADR, records how the team agreed to organise the solution. In this example, both callers use one customer settings provider and one shared cache. The provider owns freshness and database fallback.
The example decision record explains the choice and its cost. A cache failure increases database traffic. It also records alternatives and reasons to revisit the decision, such as a shorter freshness window.
Colleagues can then give their agents the same glossary, specification, and ADR while implementing separate components. One engineer builds the provider. Others integrate the request handler and scheduled worker, using the provider interface they agreed on together.
Ask each agent to flag conflicts or new architectural choices before implementing them. Bring those decisions back to the affected engineers and update the documents. Implementation will reveal things the initial discussion missed.
In my post about using AI to become a team multiplier, I described reviewing agent instructions alongside code. The reviewer can see which definitions and requirements the agent received. Check the implementation and tests against them, including whether an agent added a second cache or weakened the freshness rules.
After an agent session, ask it to extract new decisions and assumptions. The author checks that summary and updates the specification or ADR so the next colleague can find the reasoning. Before merge, the author also explains what changed and what to watch after release.
If I were managing the team, I would protect time for these discussions and ask which missing constraints or duplicate solutions they helped us catch. After a month, I would review decisions discovered late and ask another engineer to explain a recent change.
For the first session, choose one upcoming feature. Leave with definitions the team agrees on, acceptance examples, and an architecture decision colleagues can use in their next agent session.
Keep revisiting how the team communicates
Keeping each other informed and sharing what we learn takes continued effort. Agentic development is changing quickly, so the practices we use today may need to change too. I want us to keep trying different approaches and checking whether colleagues understand the decisions behind each other’s work.