In this article
Last updated September 18, 2026
4 min read
“Reuse the existing component” is one of the most common instructions given to a coding agent.
It sounds responsible. It can prevent duplication and help a change fit the repository.
It can also create a deeper coupling because the nearest existing component happens to have the right name and the
wrong responsibility.
Reuse is not a search result. It is a design decision.
The two reuse failures
The first failure is duplication.
The agent does not find the existing service, pattern, helper, or interface. It creates a second implementation that is
locally clean. The next feature now has two plausible choices.
The second failure is false reuse.
The agent finds a similar concept and extends it across a boundary. A billing status and a fulfilment status may both be
called “state.” A user identity and an organisation membership may both contain roles. Shared vocabulary does not prove
shared ownership.
False reuse can look more disciplined than duplication while creating a harder architecture.
Search for responsibility, not only names
A good reuse investigation combines several signals:
- names and keywords;
- imported symbols;
- module ownership;
- callers and dependencies;
- business rules;
- public interfaces;
- reasons recorded in architecture or feature documentation;
- tests that reveal expected behaviour.
The agent should inspect the candidate in context. Search finds possibilities. Boundary analysis decides.
Use a reuse decision record
For each meaningful candidate, record:
Candidate
What component, service, rule, or pattern was examined?
Shared responsibility
Which business responsibility is actually the same?
Different assumptions
Which data, lifecycle, permission, performance, or ownership assumptions differ?
Cost of extension
Will reuse make both callers clearer, or introduce flags, branching, and conditional behaviour?
Cost of separation
If a new component is created, what duplication appears and how will the concepts remain distinguishable?
Decision
Reuse, adapt behind a boundary, create a new concept, or escalate for architecture review.
Reason
Why is this choice safer for the system?
This record can be short. Its value is making the trade-off visible.
Watch for warning signs
Reuse deserves another look when:
- the candidate belongs to a different module;
- extension requires a boolean flag that changes its meaning;
- callers need different access rules;
- one concept has a different lifecycle;
- tests must mock away most of the existing behaviour;
- the shared abstraction name becomes vague;
- a product decision is being hidden inside a technical helper.
None of these signs automatically forbids reuse. They show that similarity may be masking a boundary.
Make new patterns earn precedent
If the team creates a new component, do not immediately treat it as the pattern for the whole repository.
Record its scope, reason, and conditions. Let later evidence show whether it deserves wider reuse.
Agents learn from accepted code. A one-off shortcut can become a repository convention if it looks current and
unqualified.
Use human review at the right boundary
The agent can gather candidates, map dependencies, compare tests, and recommend an option.
A human should own the decision when reuse changes module responsibility, public contracts, security boundaries, data
ownership, or long-term architecture.
The decision packet should show realistic options and consequences, not ask “reuse this?” after implementation already
depends on the answer.
How paqad-ai makes reuse part of planning
paqad-ai’s planning workflow includes reuse search and a reuse declaration before development. It connects the
decision to module attribution, rules, scope, and later review.
The product mechanism does not guarantee the chosen abstraction is correct.
It moves reuse from an unrecorded agent assumption into a team-visible artifact that can be challenged before the diff
makes the choice expensive.
Reuse what exists when the responsibility is truly shared.
Do not let a matching name decide the architecture.
Install paqad-ai: https://github.com/Eliyce/paqad-ai/
Source notes
- Product mechanism: first-party details from the current Eliyce/paqad-ai repository.
- OpenAI, Harness engineering, first-party discussion of explicit
architecture boundaries and legibility.