architecture-review
Skill2 starsChanged 3 months agoMITView on GitHub
Automatically use when the project is becoming more structured or reusable — code is moving out of an experiment, a module/service/repository/interface/API/database/queue/framework is being considered, responsibilities feel tangled, duplication appears, the owner asks how something should be organised, or they ask whether to adopt a framework, a library, or a pattern they have seen elsewhere. Review architecture proportionately and explain every important recommendation in plain English. Do not use for a self-contained experiment that is not being reused, for routine edits within an existing structure, or merely because a file has grown long.
85 other projects use a version of this.
Adopted by
Most recently taken up by
- lx-wnk/skillstheir own version, first seen Nov 16, 2026
- seancabalse/agentic-playbooktheir own version, first seen Nov 16, 2026
- erikperttu/steering-coding-agentstheir own version, first seen Nov 16, 2026
- Sequela02/canastatheir own version, first seen Nov 15, 2026
- OmarAlex24/audit-skillstheir own version, first seen Nov 15, 2026
- chuanglibs/Claude-Code-Game-Studios-Codextheir own version, first seen Nov 15, 2026
Used with
Projects with it also use create-stories, story-done and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
lilangMaxSkillcreate-stories
Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.
Also in 11 projects that use this
lilangMaxSkillstory-done
End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.
Also in 11 projects that use this
- +10 more from lilangMax
Other versions85 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 85
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- langwatch/langwatch★ 5ksame name
- ghuntley/loom★ 1.7ksame name
- microsoft/hve-core★ 1.6ksame name
- DataDog/dd-trace-js★ 842same name
- decebals/claude-code-java★ 763same name
- borgbase/vykar★ 726same name
- appdevforall/CodeOnTheGo★ 621same name
- owainlewis/blueprint★ 432same name
- getsentry/warden★ 424same name
75 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- .claude/rules/agents.mdAGENTS.md
- evals/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- architecture-reviewSkill
- code-reviewSkill
- evaluation-reviewSkill
- explainSkill
- interview-reviewSkill
- learning-reviewSkill
- security-reviewSkill
- start-projectSkill
- code-reviewSkill
- evaluation-reviewSkill
- explainSkill
- interview-reviewSkill
- learning-reviewSkill
- security-reviewSkill
- start-projectSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 77 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Do not reward complexity for its own sake.
- Distinctive: line 12
Start by explaining what the system currently does in plain English.
- Distinctive: line 65
If the answer is mostly no, keep the code local.
- Distinctive: line 97
When adding one, explain what the code looked like before, what pain actually appeared, and why the abstraction is now worth its cost.
- Distinctive: line 137
Do not use it:
- Distinctive: line 153
If a recommendation depends on an AI behaviour being good enough, invoke
- Very specific: line 156
If the review introduces or changes data access, AI tools, permissions, external systems, confidential information, or consequential …
- Very specific: line 157
If the review creates a meaningful reusable lesson, use learning-review after implementation or once the decision is concrete.
- Very specific: line 158
If the architecture decision is now supported by real project evidence and would be useful externally, use interview-review at the next …
- Distinctive: line 160
After the review, return to implementation.
“Common” is measured: kept by at least 6 in 10 of the 77 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Architecture Review
Review the current project as a senior legal-tech engineer and mentor.
Do not reward complexity for its own sake. The purpose is to make the system easier to understand, change, test, and trust—not to make it look more sophisticated.
Start by explaining what the system currently does in plain English.
Then assess, where relevant:
- whether the architecture matches the actual maturity of the project;
- whether responsibilities are separated for real reasons or merely by convention;
- what should remain local to one experiment versus become reusable code;
- whether deterministic logic and AI interpretation are separated sensibly;
- whether model outputs are validated before other code trusts them;
- whether source provenance is preserved where it matters;
- whether the intended user could check the output more cheaply than doing the work by hand, and whether the structure makes that easy or hard to add later;
- whether AI tools expose narrow capabilities rather than broad infrastructure access;
- whether permissions and business rules are enforced outside the model;
- whether consequential side effects have suitable human control;
- whether important actions can be audited;
- whether deterministic tests and AI evaluations match the real risks;
- whether a dependency, framework, service, or abstraction is premature;
- what would have to change before the project responsibly moves to the next maturity
stage —
docs/LEGAL_AI_DESIGN.mdholds the production-readiness questions worth being able to answer at that point, which are questions to answer rather than infrastructure to build.
Where the project has grown enough for responsibilities to need separating,
docs/LEGAL_AI_DESIGN.md sets out the four kinds — domain, application, infrastructure,
interface — and why they change for different reasons.
Two tests before proposing a boundary
Both are quick, and both are things the owner can apply themselves afterwards, which makes them worth naming rather than just applying silently.
The deletion test. Imagine deleting the module and pasting its contents back into whatever calls it. If the complexity simply vanishes, the module was passing work through, and it was costing a layer of indirection to do so. If the same complexity reappears in three different callers, it was earning its keep. This is a sharper question than "is this file too long", and it answers the one that actually matters.
One caller is a guess; two is evidence. A boundary introduced for a second use that has not appeared yet is a guess about the future, and the guess is usually wrong in a detail that makes the boundary the wrong shape. Wait for the second caller. It is far cheaper to extract a module from working code than to reshape one built for an imagined use.
The three judgements this skill exists to make
Should this be a module?
A module represents a responsibility with its own reason to change, never a file that got long. Before proposing one, ask whether you can give the responsibility a precise name, whether it has a clear input and output, whether its rules could change independently of the surrounding code, whether it is worth testing separately, whether another workflow would plausibly reuse it, and whether extracting it makes the calling code easier to read. If the answer is mostly no, keep the code local.
Names carry most of the signal. documents, deadlines, chronology, matters,
audit, tools all name a responsibility. helpers, utils, misc, and functions
name nothing, and almost always mark a boundary drawn for convenience rather than meaning.
Should this be promoted out of an experiment?
Promotion into src/legal_lab/ is a decision, not something that happens because a file
grew. Ask whether it will genuinely be used repeatedly, whether its purpose is now stable,
whether the inputs and outputs are understood, whether failure matters enough to want
tests, whether the concept is useful outside this one experiment, and whether the
capability can be given a clear domain name.
An experiment becoming long is not a reason. Neither is it working well — see
evaluation-review before promoting anything whose quality is still an impression.
Is this abstraction earning its cost?
Introduce a pattern when the problem it solves is visible, not because professional codebases contain it:
- a reusable module, once behaviour is duplicated or changing for independent reasons;
- a data-access boundary, once database details are leaking through business logic;
- a way to make a repeated request harmless (idempotency), once a retry could do the same thing twice — a run that failed after writing the deadline, retried, writing it again;
- background work, once something genuinely must happen outside the request;
- a service boundary, once workflows have become hard to reason about.
Each of those is a past-tense condition. If it has not happened yet, the abstraction is a guess.
When adding one, explain what the code looked like before, what pain actually appeared, and why the abstraction is now worth its cost. That explanation is what makes the decision contestable later; without it, the structure becomes something nobody feels able to remove.
Complexity that is not earning its keep usually looks like one of these:
- layers that merely pass arguments through;
- interfaces with only speculative future implementations;
- generic frameworks built before two real use cases exist;
- distributed infrastructure, queues, or microservices for local work;
- dependency-heavy agent frameworks wrapped around a single model call;
- elaborate configuration for values that rarely change;
- abstractions that are harder to explain than the code they replace.
Where simpler code is sufficient, prefer it and say why. Restraint is an engineering decision, and it is worth naming as one rather than leaving it to look like an omission.
Explain recommendations from the problem outward
For every material recommendation, explain:
- Practical problem — what concrete difficulty exists now?
- Recommended change — what would we alter?
- Why it helps — what becomes safer, simpler, clearer, or easier to change?
- Technical name — introduce the engineering term only if useful.
- Legal-tech relevance — why does this matter in systems lawyers rely on?
- Complexity introduced — what does this cost, and what is now harder?
- What would make us revisit it — the evidence or change that would reopen this.
- External explanation — how could the owner explain the decision in an interview?
Where there are several reasonable designs, present the meaningful options and trade-offs. Involve the owner in decisions that are valuable for them to reason about; do not make them approve trivial details.
Finish with the three highest-value improvements, ordered by impact rather than engineering fashion.
When not to use this skill
An unnecessary architecture review is not a free safety margin. It costs the owner's attention and pushes structure onto code that has not earned it, which is the exact failure this repository is trying to avoid.
Do not use it:
- for a self-contained experiment that nothing else depends on, however long the file is;
- because a file has grown — length alone is not a reason to create a module;
- for routine edits that fit the structure already there;
- to propose architecture for a problem the project does not yet have;
- because a review has not run for a while. Elapsed time is not a trigger; a change in structure or maturity is.
Length is not tangling. The signal is that responsibilities have started changing for different reasons, or that a second caller now needs the same behaviour.
Handoff to other skills
Hand off to at most one of these, and note the rest rather than running them.
- If a recommendation depends on an AI behaviour being good enough, invoke
evaluation-reviewfirst: restructuring around an unmeasured capability builds on an assumption. - If the review introduces or changes data access, AI tools, permissions, external systems, confidential information, or consequential actions, invoke
security-reviewbefore treating the design as safe enough to rely on. - If the review creates a meaningful reusable lesson, use
learning-reviewafter implementation or once the decision is concrete. - If the architecture decision is now supported by real project evidence and would be useful externally, use
interview-reviewat the next meaningful milestone.
After the review, return to implementation. Re-run this skill when the project's structure or maturity changes again; do not turn it into a review required after every edit.
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
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.

