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/evidence-matrix.md

View on GitHub
# Evidence Matrix and Decision Template

Use only the sections needed for the decision. Keep cells concise and link each
decision-relevant claim to its evidence ledger entry.

## 1. Capability brief

```markdown
## Capability brief

- User outcome:
- Capability the system must own:
- Decision question:
- Current boundary:
- Missing layer:
- Required now:
- Explicit non-goals:
- Constraints: scale, freshness, latency, quality, privacy, deployment, budget,
  licensing, data ownership
- No-change cost:
- Quality scenarios:
  - When <stimulus> occurs under <condition>, the system must <response>,
    measured by <outcome>.
```

## 2. Candidate map

```markdown
| Candidate | Type | Comparable boundary | Non-comparable boundary | Possible reuse unit | Why included |
|---|---|---|---|---|---|
| Current system | baseline | | | retain / replace | |
| Candidate A | direct / adjacent / component | | | whole / component / protocol / pattern | |
| Candidate B | commercial / open source / standard | | | | |
```

Use `non-comparable` when a product only shares the interface. Do not compare a
browser to a search index or a scraping API to a global discovery system without
making that boundary visible.

## 3. Evidence ledger

```markdown
| ID | Claim | Status | Primary source | Date or revision | Notes / confidence |
|---|---|---|---|---|---|
| E1 | | verified | | | |
| E2 | | inferred | | | reasoning; confidence |
| E3 | | unknown | none public | checked on date | evidence needed |
```

Rules:

- One row may support several matrix cells, but do not cite a source that only
  mentions a feature as proof of its hidden implementation.
- Source code evidence should identify a stable release, commit, or exact path.
- A vendor claim remains a vendor claim unless independently measured.
- Preserve contradictions; explain them instead of selecting the convenient one.

## 4. Architecture and capability comparison

Remove irrelevant rows rather than filling them with guesses.

```markdown
| Layer | Current system | Candidate A | Candidate B | Decision impact |
|---|---|---|---|---|
| Discovery / input acquisition | | | | |
| Frontier / scheduling / queues | | | | |
| Fetch / render | | | | |
| Parse / normalize / extract | | | | |
| Canonicalize / deduplicate | | | | |
| Raw and derived storage | | | | |
| Lexical / vector / graph indexes | | | | |
| Models / features / ranking | | | | |
| Query planning / serving / cache | | | | |
| Freshness / quality evaluation | | | | |
| Abuse resistance / compliance | | | | |
| Deployment / operations | | | | |
| Data ownership / dependencies | | | | |
| License / cost / lock-in | | | | |
```

For any capability that materially affects the decision, add its evidence level:

```markdown
| Capability | Declared | Implemented | Wired | Exercised | Measured | Evidence / gap |
|---|---|---|---|---|---|---|
| | yes/no/unknown | | | | | |
```

Do not collapse the maturity columns into a score. Their purpose is to expose a
missing live path, validation loop, or quality measure.

## 5. Ownership and dependency map

```markdown
request
  -> interface owned by us
  -> processing owned by us or named dependency
  -> data/index owned by us or named provider
  -> ranking owned by us or opaque provider
  -> result and provenance
```

Mark every external runtime dependency. “Self-hosted” is not equivalent to
“independent” when discovery, data, models, or control-plane services still come
from another provider.

For stateful systems, also record authority and recovery:

```markdown
| State | Authority | Durable or ephemeral | Derived from | Restart behavior | Reconciliation |
|---|---|---|---|---|---|
| | | | | | |
```

## 6. Comparable test record

```markdown
## Test record

- Question the test answers:
- Candidate versions:
- Corpus or query set:
- Expected result and scoring rule:
- Environment and hardware:
- Commands or requests:
- Raw result location:
- Result:
- Limitations:
```

If no fair test ran, replace the section with the exact blocker and the future
test that would remove the uncertainty.

## 7. Adoption viability

Include this section when the recommendation introduces an open-source project,
vendor, hosted service, or other externally governed dependency.

```markdown
| Area | Evidence | Risk / decision impact |
|---|---|---|
| Maintenance and releases | | |
| Governance and contributor concentration | | |
| Tests, security, and release provenance | | |
| License and distribution | | |
| Upgrade, operations, and support | | |
| Switching cost and exit path | | |
```

Automated health or security scores are inputs, not acceptance decisions. Check
whether each underlying heuristic applies to this project and workload.

## 8. Decision record

```markdown
## Decision

- Disposition: adopt / adapt / build / defer / retain
- Selected direction:
- Why it fits the current capability brief:
- Reuse unit: whole system / subsystem / component / protocol / data model / pattern
- Quality trade-offs accepted:
- What not to copy:
- Rejected alternatives and reasons:
- Accepted risks:
- Unknowns that remain:
- Evidence that would reverse the decision:
- Smallest validation milestone:
- Verification command or observable success condition:
- Exit path or review trigger:
- Handoff to architecture-foundation: selected components, constraints,
  ownership decisions, unresolved questions, prohibited dependencies
```

Avoid a score that implies false precision. When weighted scoring is truly
useful, ask the user to confirm the criteria and weights before calculating it.
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: 322kUpdated 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