Skip to content

majiayu000/spellbook / skills/architecture-research

architecture-research

Verified

Evidence-driven architecture research for understanding real systems and making technical decisions. Use when doing architecture landscape studies, source-backed system archaeology, build-vs-buy or adopt/adapt/build decisions, open-source and commercial comparisons, revisiting an earlier architecture choice, or handling requests such as 架构调研, 架构选型, 竞品架构, 技术尽调, 同类方案, 开源替代, how is X built, and what should we learn from X. Do not use for small mechanical changes, market-only discovery, or detailed design after the technology direction is already fixed.

FileKindSize
SKILL.mdskill md11.1 KB
references/architecture-lenses.mdmarkdown6.5 KB
references/evidence-matrix.mdmarkdown5.4 KB

references/architecture-lenses.md

View on GitHub
# Architecture Research Lenses

Use only the lenses that can affect the current decision. They are questions for
investigation, not a checklist that every report must reproduce.

## 1. Boundary and ownership

Separate a system's visible interface from the capability underneath it.

- What outcome does the system produce, and where does its responsibility end?
- Which inputs, datasets, indexes, models, queues, and control services are
  owned, licensed, hosted, or supplied by somebody else?
- Is the candidate a whole system, an orchestration layer, a component, a
  protocol implementation, or only a client?
- Does self-hosting remove an external dependency, or merely relocate the
  interface and scheduler?
- Which layer is differentiating enough that ownership is a requirement?

Trace three paths when they exist:

```text
data path:       input -> acquisition -> transform -> state -> result
control path:    intent -> schedule/policy -> execution -> retry/reconcile
operations path: deploy -> observe -> recover -> upgrade -> retire
```

## 2. Authority, state, and recovery

Persistent data is not automatically authoritative or sufficient for recovery.

- What is the source of truth for intent and current state?
- Which stores are authoritative, cached, projected, historical, or ephemeral?
- Can two stores disagree? Which one wins, and how is divergence detected?
- What exact state and input must survive a restart to continue safely?
- Does recovery replay events, resume a checkpoint, reconstruct from an external
  tracker, or start a new equivalent task?
- What reconciliation loop corrects stale local state against live remote truth?
- Are transitions idempotent, and what prevents duplicate work or false
  completion?

Use failure scenarios, not only normal diagrams: process crash, partial write,
stale checkpoint, provider timeout, retry after side effect, unavailable
dependency, schema change, and rollback.

## 3. Capability maturity

Do not count a capability merely because a type, trait, module, configuration,
or document exists. Record the highest level supported by evidence:

1. **Declared**: named in docs, types, interfaces, or configuration.
2. **Implemented**: working code exists behind the declaration.
3. **Wired**: the supported runtime path invokes it with real inputs.
4. **Exercised**: tests or runtime evidence cover the intended path and failures.
5. **Measured**: quality and operations are observed against a defined target.

This ladder is not a numeric product score. Use it to expose missing links. For
example, a provider adapter may be implemented but absent from the registry; a
learning pipeline may collect events but lack attribution, decision state, and
outcome verification.

## 4. End-to-end lifecycle

Trace the complete lifecycle rather than stopping at the interesting algorithm:

```text
discover/acquire
  -> validate/normalize
  -> persist/index
  -> decide/rank/execute
  -> deliver
  -> observe/evaluate
  -> correct/learn/retire
```

At every stage ask:

- What is the input contract and failure contract?
- Where is provenance retained or lost?
- How are freshness, duplication, ordering, and partial success handled?
- Who owns quality, and what closes the feedback loop?
- Is the stage online, batch, human-gated, or only described in a prompt?

An architecture is incomplete for the named capability when an essential stage
has no owner, input, state transition, or validation path.

## 5. Quality scenarios and trade-offs

Turn vague goals into scenarios:

```text
When <stimulus> occurs
under <operating condition>,
the system must <response>
measured by <threshold or observable outcome>.
```

Examples include restart recovery, sudden load, provider failure, data deletion,
new model integration, regional outage, or a tenfold corpus increase.

For each high-priority scenario identify:

- Architectural decisions that enable the response.
- **Sensitivity points** where a small design change materially affects a
  quality attribute.
- **Trade-off points** where improving one quality worsens another.
- Risks, non-risks, and the evidence needed to validate the response.

This adapts the scenario and trade-off discipline of the
[CMU SEI Architecture Tradeoff Analysis Method](https://www.sei.cmu.edu/library/architecture-tradeoff-analysis-method-collection/)
without requiring a formal multi-day ATAM review for every decision.

## 6. Operational and economic reality

- What are steady-state and failure-state operational burdens?
- Which queues, rate limits, retries, caches, and backpressure controls exist?
- What are the unit economics at the current workload and next credible scale?
- Which complexity is intrinsic to the capability, and which came from another
  organization's history or hyperscale constraints?
- What skills, on-call ownership, observability, and incident response are
  required?
- Is the build path staged so each milestone is independently useful?

Compare the current scale horizon, not an imagined maximum. Record the trigger
that would justify a more complex design later.

## 7. Adoption viability

Technical fit is necessary but not sufficient for adopting a third-party system.

- Is the project maintained, released, documented, tested, and upgradeable?
- Is governance concentrated, stable, or vulnerable to a single sponsor?
- Are security reporting, dependency updates, CI, code review, and release
  provenance appropriate for this use?
- What license, hosting, data, and vendor terms constrain use or redistribution?
- Can the team operate, patch, fork, or replace it if upstream stalls?

[OpenSSF Scorecard](https://github.com/ossf/scorecard) can supply reproducible
security-health signals, but its own check documentation notes detection limits
and context-dependent applicability. Treat each check as evidence to inspect,
not a universal acceptance threshold.

## 8. Reversibility and review

- Is the choice a reversible component decision or a one-way data/control-plane
  commitment?
- What data export, compatibility boundary, or replacement seam makes exit
  possible?
- What is the smallest validation milestone before deeper commitment?
- Which assumption, metric, price, license, maintenance event, or scale threshold
  should trigger a new review?
- What evidence would reverse the recommendation?

Architecture changes over time. The
[AWS Well-Architected review guidance](https://docs.aws.amazon.com/wellarchitected/latest/framework/the-review-process.html)
recommends deeper inspection for hard-to-reverse decisions and lightweight,
continuous review as systems evolve. Store the decision date and review trigger
when the evidence is likely to change.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall