agentleFS
hemapriyan-rkhemapriyan-rk/claude-rigor-skills/skills/architecture-design/SKILL.md

architecture-design

Skill1 starsChanged 51 days agoMITView on GitHub

Design or review a system architecture with explicit trade-offs, failure modes, a threat model, and break scenarios. Use for "how should I architect X" questions involving scale, distributed state, edge/cloud, ML, or agents. Not for scaffolding a single simple service.

33 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use results-report, daily-coding and 9 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.
  • Galaxy-DawnSkill

    results-report

    This skill should be used when the user asks to "write an experiment report", "summarize experimental results", "do experiment retrospection", "write a results report", "写实验总结报告", "写实验复盘", or mentions turning completed experiment artifacts into a structured, decision-oriented research report. It assumes strict analysis should come from `results-analysis` first.

    Also in 3 projects that use this

  • Clay-HHKSkill

    daily-coding

    Daily coding assistant that auto-triggers when writing/modifying code, providing a core checklist.

    Also in 3 projects that use this

  • Clay-HHKSkill

    kaggle-learner

    This skill should be used when the user asks to "learn from Kaggle", "study Kaggle solutions", "analyze Kaggle competitions", or mentions Kaggle competition URLs. Provides access to extracted knowledge from winning Kaggle solutions across NLP, CV, time series, tabular, and multimodal domains.

    Also in 3 projects that use this

  • kharlamenkodevSkill

    bug-detective

    Also in 4 projects that use this

  • Google CloudSkill

    citation-verification

    Verify that citations in a document resolve to real records and that claimed titles match. Use before trusting a document's reference list.

    Also in 4 projects that use this

  • MicrosoftSkill

    web-design-reviewer

    This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level.

    Also in 4 projects that use this

  • +2 more from Clay-HHK

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 27 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Get the numbers, once: If load, latency, availability, or cost targets are missing, ask for them in a single message of at most three …

    line 13
  2. Distinctive:

    Reviewing an existing design?: Read the design doc or code you were given before proposing anything.

    line 14
  3. Very specific:

    Load the checklist with the requirements: Before step 4, read references/failure-modes.md from this skill's base directory.

    line 15
  4. Distinctive:

    Write each as one line, for example: *"Ride requests are written to Postgres synchronously (consistency) and fanned out to drivers through …

    line 31
  5. Distinctive:

    If a design can't say which side it picked, the decision was deferred to production.

    line 33
  6. Distinctive:

    If any answer is "undefined," that is the design's weak point.

    line 56
  7. Distinctive:

    Keep it as short as the stakes allow.

    line 72

“Common” is measured: kept by at least 6 in 10 of the 27 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.

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

Architecture Design

A diagram of boxes and arrows is not an architecture. An architecture is a set of trade-offs someone decided on purpose, plus an account of how the system fails. This skill produces both.

1. Set scope and budget

  • Match depth to the stakes. A prototype or internal tool gets the short form: requirements, the three most important trade-offs, the top five failure modes, and the weakest point. A production system, anything handling money or personal data, or anything with ML or edge components gets the full form below.
  • Get the numbers, once. If load, latency, availability, or cost targets are missing, ask for them in a single message of at most three questions. If the user can't or won't answer, state your assumptions as numbers and continue. Don't stall.
  • Reviewing an existing design? Read the design doc or code you were given before proposing anything. Don't redesign parts that already work; say what you'd keep.
  • Load the checklist with the requirements. Before step 4, read references/failure-modes.md from this skill's base directory. It lists failure modes and threats by component type, so you check against it instead of recalling them from scratch.

2. Requirements

  • Functional: what the system must do, in a few bullets.
  • Non-functional, as numbers: throughput, latency target (with percentile), availability, data durability, consistency needs, cost ceiling, and power or bandwidth budget for edge parts. "Fast" and "scalable" aren't requirements.

3. Decide the trade-offs

Name each decision and what it gives up. At minimum:

  • Consistency vs. availability when the network partitions, and where in the system that line sits.
  • Synchronous vs. asynchronous calls between components, and what happens when a downstream service is slow.
  • Edge vs. cloud placement, and what happens when the connection between them drops.
  • Who owns each piece of state, and which copy wins when two disagree.

Write each as one line, for example: "Ride requests are written to Postgres synchronously (consistency) and fanned out to drivers through a queue (availability). A queue outage delays dispatch; it doesn't lose rides."

If a design can't say which side it picked, the decision was deferred to production.

4. Components, data flow, and failure modes

  • Draw the components and data flow as a Mermaid diagram, and list what crosses each boundary (data, format, protocol).
  • For each component, use the checklist to state what happens when it is down, slow, overloaded, or fed bad data, and whether the system degrades or fails. For any ML component, state the fallback for low-confidence or out-of-distribution input.

5. Threat model

For each trust boundary in the diagram: what can an attacker send across it, what control stops them, and what stays exposed after that control. Include the ML and sensor threats from the checklist if those components exist.

6. Observability

Name the few signals that would detect each top failure mode from step 4, and which ones page someone. A failure you can't detect will be found by users.

7. Break it before calling it done

Walk through three concrete scenarios and say what breaks first in each:

  1. 10× the expected peak load.
  2. The most important stateful component unavailable for 15 minutes.
  3. A malicious or malformed input on the most exposed path.

If any answer is "undefined," that is the design's weak point. Say so.

Output

# Architecture: <system>
## Requirements (numbers, with stated assumptions)
## Trade-offs (one line each: decision → what it gives up)
## Diagram (mermaid) and boundary data
## Failure modes (component → down / slow / bad data → behavior)
## Threat model (boundary → attack → control → residual risk)
## Observability (signal → failure it detects → pages?)
## Break scenarios (scenario → what breaks first)
## Weakest point

Keep it as short as the stakes allow. A table row beats a paragraph.

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.