Codebase Patterns

Codebase Patterns

Follow the repository's current conventions without introducing an unnecessary third pattern. Treat pattern selection as an evidence-gathering task, not a style preference.

Establish the comparable patterns

Before implementing a change that touches an established layer or responsibility:

1. Read applicable repository instructions, architecture decisions, and nearby tests.
2. Find several examples performing the same architectural role in the same subsystem. Do not infer a conflict from examples serving materially different purposes.
3. Identify the meaningful differences between the candidate patterns and which differences affect the requested change.

If one applicable pattern is clearly consistent, use it without expanding the investigation unnecessarily.

Resolve competing patterns

When multiple applicable patterns exist, inspect their provenance with focused git history and blame. Examine the commits that introduced or substantially changed representative examples, not only each file's latest timestamp.

Use evidence in this order:

1. Explicit user direction and current repository instructions, architecture decisions, public contracts, and tests.
2. Functional correctness and compatibility with the target subsystem.
3. The pattern consistently used by nearby code with the same responsibility.
4. Repeated adoption in newer changes. Prefer a newer pattern when history indicates that it is replacing an older convention.
5. Relevant CODEOWNERS or maintainer involvement in those changes. Treat this as supporting evidence, especially when an older example was introduced outside the owning team.
6. Simplicity, clarity, and smaller surface area when the candidates are otherwise functionally and historically equivalent.

Recency is strong evidence, not proof. Do not treat a recent one-off experiment, generated or vendored code, an incomplete migration, or a change later reverted as the new convention. A commit author does not become a code owner merely by changing a file. If no CODEOWNERS file or matching rule exists, omit ownership from the decision rather than guessing.

Useful focused history checks include git log -- , git blame , and git show . Use broader searches only when the local evidence is insufficient.

Handle unresolved inconsistency

If multiple patterns remain actively used in recent work and the evidence does not establish a winner:

1. Tell the user that the repository has competing current conventions.
2. Show the alternatives with concise evidence, including representative paths and relevant history.
3. Explain the material tradeoff, recommend an option when the evidence supports one, and ask the user to choose when the decision would establish a convention.
4. Offer to record the decision in the repository's existing agent instructions, architecture decisions, or convention documentation so future contributors and agents can follow it. Do not create or change that documentation without the user's approval.

Do not silently choose a third design. If none of the existing patterns applies, say so and propose the smallest necessary extension separately from the implementation.

Implement consistently

• Apply the selected pattern across every touched layer where it is relevant.
• Preserve differences required by the new behavior; do not copy incidental details blindly.
• Avoid opportunistic migration of unrelated code unless the user requests it.
• Match tests to the selected current testing pattern for the same type of behavior and boundary.

Review the result

Before presenting the work:

1. Review the diff against the representative precedent and confirm it does not introduce another convention.
2. Run the existing checks relevant to the change when they are available and within scope.
3. Name the pattern followed and briefly identify the evidence used when the choice was not obvious.
4. Surface any remaining ambiguity or assumptions in the handoff.

Treat the user's review of the diff as the acceptance gate for the convention choice; passing automated checks alone does not establish that the chosen pattern is preferred.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marksgerasimovs
• Source: marksgerasimovs/skills
• License: MIT

Install and usage instructions live in the source repository linked above.