AGENT SKILL

system-design-case

Document a system you designed as an interview case, with a design doc, decision records (why plus trade-offs), archify architecture/sequence diagrams that stay in sync, and a generated page to present it on screen share. Use when starting a case, recording or revising a design decision, adding a flow diagram to a case, presenting a case, or rehearsing a case for a reverse system design interview.

License 许可
MIT
最近更新
2026-10-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
system-design-case
description
Document a system you designed as an interview case, with a design doc, decision records (why plus trade-offs), archify architecture/sequence diagrams that stay in sync, and a generated page to present it on screen share. Use when starting a case, recording or revising a design decision, adding a flow diagram to a case, presenting a case, or rehearsing a case for a reverse system design interview.

02 资源文件 7

03 SKILL.md 正文

System design case

A case is one system you designed, documented so you can present it in two minutes and defend every choice under questioning. Each artifact owns one meaning:

  • README.md: the narrative, from the pitch down to the deep dives.
  • decisions/D-NN-<slug>.md: why each choice was made and what it cost.
  • diagrams/: archify JSON sources (the diffable truth) and their rendered HTML.
  • index.html: the page you share on screen, generated from the three above; never edit it by hand.
cases/index.html                       ← generated hub linking every case
cases/<slug>/
  README.md                            ← from templates/case.md
  decisions/D-01-<slug>.md             ← from templates/decision.md
  diagrams/architecture.json → .html
  diagrams/<flow>.sequence.json → .html
  figures/                             ← optional diagram-design static figures
  index.html                           ← generated by scripts/build-page.mjs

Cases live under cases/ in the interview-prep repo (/home/heynemann/src/doordash); paths below are relative to that repo root. cases/ is its own git clone of heynemann/cases (private): commit case changes there, with .evidence/ git-ignored. Case diagrams are living documents rendered in place at these stable paths, which takes precedence over archify's timestamped .archify/ folders. Worked example: cases/example-order-dispatch/.

Starting a case

  1. Grill the user. Copy templates/case.md to the case's README.md, then read the grilling skill and references/interview-map.md and run a grilling session whose design tree starts from the map's branches. Facts about a past system come only from the user: a recommended answer is a hypothesis for them to correct, never recorded unconfirmed; look facts up yourself only in a repository the user points you to. After each round, write the settled answers where the map says (README sections, decisions/D-NN-<slug>.md from templates/decision.md, numbered from D-01), so stopping mid-session loses nothing. The session ends when every branch is settled; list every TBD(<question>) back to the user.

  2. Diagrams: read the archify skill, then author diagrams/architecture.json and one sequence per key flow (usually the happy path plus the hardest failure path). Set meta.output to the matching .html path and run from the repo root, with a fresh timestamp each time the JSON changes (archify will not overwrite the previous run's check results, so retries of unchanged JSON reuse the same folder):

    node <archify-skill-dir>/bin/archify.mjs finalize <type> cases/<slug>/diagrams/<name>.json cases/<slug>/diagrams/<name>.html \
      --quality showcase --out-dir cases/<slug>/diagrams/.evidence/<name>-<YYYYMMDD-HHMMSS> --json
    

    A sequence segment's label is drawn 22px above its from and shifts up past any colliding message, so leave about 30px between each segment's from and the message or segment above it. Passing gates do not catch a misplaced label; look at a visual-check capture before calling a new sequence done.

  3. Wire the links per Sync below.

  4. Build the page per Presenting below.

Done when: every interview-map branch is settled, every decision-log row has a record, every record's Affects IDs exist in its diagram, every accepted decision is wired per Sync, every diagram's finalize passes, the page is rebuilt, and every TBD has been reported.

Decision records

The interview value is the reasoning, so each record answers what a senior interviewer probes:

  • Title states the choice, not the topic: "Batch dispatch every few seconds instead of greedy per-order assignment".
  • Options include the alternative the interviewer will suggest ("why not just use X?"), each with its wins and costs.
  • Deciding force: the one constraint or number that tipped it. If the user can't name it, ask until they can; that gap is exactly where an interview goes wrong.
  • Cost accepted: what got worse, by how much, and how it was contained.
  • Revisit when: the observable signal that would flip the decision.

Supersede, keep history. A changed decision gets a new record; the old one keeps its text with Status: superseded by D-NN. "We started with X and moved to Y because Z" is the strongest story in a reverse interview.

Sync

Links run both ways, and archify component/participant IDs are the stable join keys (renaming one breaks links):

  • Decision → diagram: the record's Affects line names the diagram file and the IDs it changes; its first architecture ID is the decision's anchor node.
  • Diagram → decision: the anchor component's tag is "D-NN · <2-3 words>", and the architecture's only card is "Decisions", one item per accepted decision: "D-NN · <choice>: <what it bought>, <what it cost>". Sequence participants have no tag, so a sequence cites D-NN in its card items.
  • README → interactive diagram: the deep-dive menu links each decision to diagrams/architecture.html#focus=<anchor-id>, which dims the rest and opens the anchor's detail panel with its tag and connections. #route=<from-id>~<to-id> highlights a whole path for flow questions.
  • README: one decision-log row per record (ID, decision, deciding force, cost accepted).

Archify still validates meta.views but renders nothing from it; use the links above instead.

When a decision changes: grill the map's Decisions branch for the new record (and any branch the change reopens), supersede the old record, edit the JSON of every diagram in Affects (tag, card item), rerun finalize for each, update the log row and deep link, and rebuild the page.

Presenting

Run from the repo root after any change to the markdown or diagrams:

node /home/heynemann/.omp/profiles/doordash/agent/skills/system-design-case/scripts/build-page.mjs cases/<slug>

It writes cases/<slug>/index.html and rebuilds the hub cases/index.html, which lists every case; pass cases instead of cases/<slug> to rebuild all of them. Open the hub as a local file, pick the case, and share that browser tab:

  • The narrative scrolls beside a pinned, fully interactive archify viewer (path tracing, lens, map, node details all work in place). On each decision it shows archify's focus on the anchor (superseded decisions are stamped historical); on each key flow it switches to that flow's sequence diagram. Each state loads once and keeps whatever you traced in it when you scroll back.
  • F (or Expand) opens the current state full-screen for deep-dive questions; Esc closes it. README links with #route=… open that path live in the panel.
  • The D-NN chips and Ctrl/⌘K jump to any decision when the interviewer asks about it.
  • The README's "Interview prep" section is never rendered, so pitch notes and hard-question answers stay private.

build-page warns when an Affects id is not a node in its diagram's archify JSON, since archify's focus then has nothing to show.

The page reads the template structure (## section names, the **Status:**/**Affects:** line, the Options table with the chosen option in bold), so keep records in template shape for them to render.

Rehearsing

Play the interviewer with the grilling skill (what /grill-me runs), aimed at the case: pitch, then each record's cost and revisit-when, then failure modes, then the map's branches the README answers thinnest. Write every answer that holds up back into its record or the README's hard-questions list.

04 同仓库更多 Skills

heynemann
heynemann/dotfiles-stow

unity-scriptableobjects

Architect Unity 6.3 LTS data and decoupling with ScriptableObjects: config/data assets, shared runtime variables, event channels, and runtime sets/registries. Use when designing data-driven systems, replacing singletons/managers, creating .asset data with CreateAssetMenu, or when the user mentions ScriptableObject, SO architecture, or data assets.

★ 0
heynemann
heynemann/dotfiles-stow

unity-package-management

Adds, removes, upgrades, and discovers Unity (UPM) packages from outside the Editor. Use for headless or CI package installs, verifying package IDs and versions, or choosing which packages a game needs. The Unity CLI doesn't manage packages.

★ 0
heynemann
heynemann/dotfiles-stow

unity-input-system

Wire player input in Unity 6.3 LTS with the Input System package: Input Actions, action maps, the PlayerInput component, and reading values via callbacks or polling. Use when the project has a .inputactions asset or com.unity.inputsystem, or when the user mentions the Unity Input System, InputAction, action maps, PlayerInput, control schemes, or rebinding.

★ 0
heynemann
heynemann/dotfiles-stow

unity-ecs-patterns

Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizing performance, or working with large entity counts.

★ 0
heynemann
heynemann/dotfiles-stow

unity-csharp-scripting

Write Unity 6.3 LTS C# gameplay scripts: the MonoBehaviour lifecycle (Awake/OnEnable/Start/Update/FixedUpdate/LateUpdate), GameObject and component access, coroutines, and Inspector serialization. Use when creating or editing .cs scripts in a Unity project, or when the user mentions MonoBehaviour, Start/Update, GetComponent, SerializeField, coroutines, or "Unity script".

★ 0
heynemann
heynemann/dotfiles-stow

unity-cli

Controls the Unity Editor and projects from the command line, driving a running Editor to edit scenes and assets or run C#. Use when asked to install or manage Editors, licenses, or projects, set up version control, build, test, configure the Unity MCP server, or run any unity command.

★ 0