agentleFS
Joyboy-dyJoyboy-dy/felicio-ai-skills/skills/codebase-architecture-guardian/SKILL.md

codebase-architecture-guardian

Skill0 starsChanged 3 months agoMITView on GitHub

Use when inspecting an unfamiliar repository, deciding where new code belongs, reviewing architectural boundaries, preventing dependency drift, planning a cross-cutting refactor, or checking that a change fits the codebase's existing structure.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not use this skill to impose a preferred framework layout.

    line 14
  2. Distinctive:

    Discover before prescribing: Read manifests, configs, entry points, representative modules, tests, and documentation before deciding where …

    line 18
  3. Very specific:

    Minimize new concepts: Do not create utils, services, core, shared, or abstraction layers merely because they are common names.

    line 20
  4. Distinctive:

    Start with a compact structural scan:

    line 29
  5. Very specific:

    Read references/folder-responsibilities.md when the repository has ambiguous folder responsibilities.

    line 60
  6. Very specific:

    Read references/anti-patterns.md when one of these smells appears.

    line 74
  7. Distinctive:

    Do not create abstractions “for future use.”

    line 85
  8. Distinctive:

    import/public API changes.

    line 92
  9. Very specific:

    Read references/refactoring-playbook.md for larger moves.

    line 98
  10. Distinctive:

    Use the repository's own commands.

    line 102
  11. Distinctive:

    Search for stale imports and old names after moves.

    line 110
  12. Very specific:

    Use references/output-templates.md when a formal architecture/refactor report is requested.

    line 123
  13. Very specific:

    After ownership and boundaries are clear, hand implementation details to the most specific relevant skill.

    line 137

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Codebase Architecture Guardian

Protect architectural coherence by discovering the repository's actual boundaries before proposing new ones.

Use when

Activate for repository archaeology, ownership questions, folder/module placement, dependency direction, duplicated abstractions, cross-cutting refactors, architecture reviews, or changes that touch several layers.

Do not use this skill to impose a preferred framework layout. A repository's current conventions are evidence; a generic template is not.

Non-negotiable principles

  1. Discover before prescribing. Read manifests, configs, entry points, representative modules, tests, and documentation before deciding where code belongs.
  2. Prefer existing ownership. Extend the module that already owns the behavior unless there is clear evidence that ownership is wrong.
  3. Minimize new concepts. Do not create utils, services, core, shared, or abstraction layers merely because they are common names.
  4. Respect dependency direction. High-level/domain logic should not become coupled to delivery/UI/infrastructure details without a deliberate boundary.
  5. Refactor from evidence. Duplication, cyclic dependencies, change friction, test difficulty, or unclear ownership justify structural work; aesthetics alone usually do not.
  6. Preserve public contracts by default. Break APIs, imports, routes, persistence formats, or configuration only when the task requires it and migration is planned.

Workflow

1. Inventory the repository

Start with a compact structural scan:

python scripts/inventory_codebase.py <project-root> --json

Then inspect the files that establish conventions:

  • package/project manifests and lockfiles;
  • framework/build/test/lint/type configs;
  • source roots and entry points;
  • routing/controllers/handlers or equivalent delivery boundaries;
  • domain/model/business logic;
  • persistence/integration adapters;
  • shared components/utilities;
  • tests and fixtures;
  • architecture docs, ADRs, contributor instructions, agent instructions.

The script is only a map. Read representative code before drawing architectural conclusions.

2. Build an ownership map

For every concept affected by the task, answer:

  • Which module currently owns the data or behavior?
  • Who calls it?
  • What does it depend on?
  • Where is it tested?
  • Which public surface exposes it?
  • Is there already an adjacent pattern for the requested change?

Read references/folder-responsibilities.md when the repository has ambiguous folder responsibilities. Use it as a reasoning framework, never as a prescribed folder tree.

3. Trace dependency direction

Trace the smallest relevant path from caller to owned behavior to external side effect. Watch for:

  • domain logic imported from UI/view code;
  • low-level modules importing high-level orchestration;
  • circular imports;
  • feature modules reaching into another feature's internals;
  • shared modules becoming dumping grounds;
  • data-access details leaking through several layers;
  • business rules duplicated at multiple boundaries.

Read references/anti-patterns.md when one of these smells appears.

4. Choose the smallest coherent change

Prefer, in order:

  1. extend an existing module/pattern;
  2. extract a local helper with one owner;
  3. introduce a reusable boundary only after multiple consumers or a stability/testing reason exists;
  4. perform broad restructuring only when the user requested it or evidence shows the current structure blocks the task.

Do not create abstractions “for future use.”

5. Plan migrations explicitly

For structural changes, list:

  • files/modules moved or introduced;
  • import/public API changes;
  • compatibility layer if needed;
  • tests that prove preserved behavior;
  • sequencing to keep the repository buildable;
  • cleanup that happens only after consumers migrate.

Read references/refactoring-playbook.md for larger moves.

6. Validate

Use the repository's own commands. At minimum, when available:

  • formatter/lint;
  • typecheck or compiler;
  • unit/integration tests touching changed boundaries;
  • architecture/dependency checks already present;
  • build/package checks for public export changes.

Search for stale imports and old names after moves. Never claim architectural safety from a passing build alone.

Architecture review output

Separate the report into:

  • Observed structure — facts from the repository;
  • Boundary risks — concrete coupling/ownership issues with file evidence;
  • Recommended change — smallest coherent action;
  • Migration impact — public contracts, imports, data/config effects;
  • Validation — checks actually performed;
  • Open uncertainty — anything not proven from available files/tests.

Use references/output-templates.md when a formal architecture/refactor report is requested.

Common failure modes

  • Assuming a src/, app/, features/, monorepo, clean architecture, or hexagonal layout without evidence.
  • Splitting files because they are long rather than because responsibilities differ.
  • Moving code into “shared” while preserving hidden feature coupling.
  • Creating a service/repository/interface trio for simple local logic with one consumer.
  • Rewriting a stable area while implementing an unrelated feature.
  • Treating folder names as architecture without tracing imports and runtime ownership.
  • Ignoring generated code, package exports, tests, migrations, or build tooling during a move.

Handoff

After ownership and boundaries are clear, hand implementation details to the most specific relevant skill. For frontend implementation use senior-frontend-engineering; for Next.js routing/rendering structure use nextjs-architecture-pattern; for container packaging use container-compose-ghcr-deployment.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.