seudesign
Practical system design skill: design docs, architecture reviews, mock interviews, capacity estimation.
Open source Open in the app JSON README (API)
About
Practical system design skill: design docs, architecture reviews, mock interviews, capacity estimation.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- seuput0705
- Origin
- gemini
- Category
- ferramentas
- Version
- 3.0.0
- Last push
- 2026-09-05T02:33:49Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-09-05 09:00:35
- Origin id
seuput0705/seudesign
README
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
<img src="assets/logo.png" width="360" alt="seudesign">
</picture>
</p>
<h1 align="center">seudesign</h1>
<p align="center">
<em>Don't read system design. Run it.</em><br>
Portable system design workflows for design docs, architecture reviews,
mock interviews, and capacity estimation.
</p>
<p align="center">
<img src="https://img.shields.io/github/stars/SeuPut0705/seudesign?style=flat-square&color=111111&label=stars" alt="Stars">
<img src="https://img.shields.io/badge/package-Claude%20Code%20%C2%B7%20Codex%20%C2%B7%20Gemini-111111?style=flat-square" alt="Claude Code, Codex, and Gemini package">
<img src="https://img.shields.io/badge/cases-22-111111?style=flat-square" alt="22 case studies">
<img src="https://img.shields.io/github/actions/workflow/status/SeuPut0705/seudesign/ci.yml?style=flat-square&color=111111&label=ci" alt="CI">
<img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
</p>
<p align="center">
<sub>English · <a href="README.ko.md">한국어</a> · <a href="README.ja.md">日本語</a> · <a href="README.zh.md">中文</a></sub>
</p>
---
seudesign is a **working skill**, not a prompt collection. Its thin router
loads only the workflow and references needed for the current request. The
agent answers in your conversation language.
## Workflows
| Mode | Outcome |
|---|---|
| `design <system>` | A focused architecture decision or full design grounded in workload and failure boundaries |
| `review [path]` | Read-only architecture audit with severity, `file:line` evidence, impact, and the smallest fix |
| `interview [problem]` | Mock interview with progressive hints and rubric scoring |
| `estimate <target>` | RPS, bandwidth, storage, memory, and sizing limits with explicit assumptions and unknowns |
Reuse supplied context, ask only for decisions that are blocked, and complete
explicit sequences such as review followed by an improvement design. Chat is
the default; requested files use the supplied path or a suitable workspace
path. An update request authorizes a scoped edit of that document.
## Invoke it on each host
| Host | Invocation |
|---|---|
| Claude Code plugin | `/seudesign:sdp design a chat service` |
| Codex | `$sdp design a chat service`, or open `/skills` and select `sdp` |
| Gemini CLI extension | Ask naturally, for example “Use the sdp skill to review this repository.” |
| GitHub Copilot CLI, OpenCode, Cursor, and other AGENTS.md hosts | Ask naturally. Use a host selector only when that host documents it. |
Do not assume that one host's slash command works on another host.
## Install
### Claude Code
Send these as separate prompts:
```text
/plugin marketplace add https://github.com/SeuPut0705/seudesign.git#v3.0.0
```
```text
/plugin install seudesign@seudesign
```
### Codex
```bash
codex plugin marketplace add SeuPut0705/seudesign --ref v3.0.0
codex plugin add seudesign@seudesign
```
This installation selects the immutable `v3.0.0` release. The marketplace and
plugin come from that same snapshot. Only stable release versions are managed.
Start a **new Codex session** after installation so the bundled skill is
loaded. Invoke it with `$sdp` or the `/skills` selector.
### Gemini CLI
```bash
gemini extensions install https://github.com/SeuPut0705/seudesign --ref v3.0.0
```
The extension loads [AGENTS.md](AGENTS.md), so invoke the four workflows in
natural language after starting a new Gemini session. Add `--ref v3.0.0` or a
full commit SHA for an immutable install.
### Update an existing installation
```bash
claude plugin update seudesign@seudesign
codex plugin marketplace upgrade seudesign
codex plugin add seudesign@seudesign
gemini extensions update seudesign
```
Run only the command for your host, then start a new session. Codex separates
marketplace refresh from plugin reinstall, so both Codex commands are required.
These update commands preserve a configured Git ref. To move an intentionally
pinned Claude Code, Codex, or Gemini install to `NEW_TAG`, reconfigure that pin explicitly:
```bash
claude plugin marketplace remove seudesign
claude plugin marketplace add "https://github.com/SeuPut0705/seudesign.git#NEW_TAG"
claude plugin install seudesign@seudesign
codex plugin marketplace remove seudesign
codex plugin marketplace add SeuPut0705/seudesign --ref NEW_TAG
codex plugin add seudesign@seudesign
gemini extensions uninstall seudesign
gemini extensions install https://github.com/SeuPut0705/seudesign --ref NEW_TAG
```
### Repository-aware hosts
Clone and open the repository. OpenCode, Cursor, and other agents that load
[AGENTS.md](AGENTS.md) can route natural-language system design requests to
the skill. For GitHub Copilot CLI, use its documented extension or
skill-directory flow rather than copying another host's command syntax.
### Generic skill-directory installer
```bash
SDP_REF="${SDP_REF:-v3.0.0}"
(
SDP_INSTALLER=$(mktemp "${TMPDIR:-/tmp}/seudesign-install.XXXXXX") &&
trap 'rm -f "$SDP_INSTALLER"' 0 HUP INT TERM &&
curl -fsSL --connect-timeout 10 --max-time 120 \
"https://raw.githubusercontent.com/SeuPut0705/seudesign/$SDP_REF/install.sh" -o "$SDP_INSTALLER" &&
REF="$SDP_REF" sh "$SDP_INSTALLER"
)
```
The installer stages and validates the skill before activation, recognizes
the exact package-owned regular-file inventory and owned installs, and rolls
back if activation or its root postcondition fails.
Concurrent invocations for the same `DEST` are serialized by a bounded-wait
target lock, and a symlink used as `SOURCE_DIR` is copied into an independent
real directory. Its controls are:
- `DEST=/path/to/skills` changes the parent skills directory.
- `SDP_REF=<commit>` before the public snippet pins both the installer code and
its archive to the same selector. Use a full commit SHA for an immutable,
reproducible install; `main`, branches, and movable tags can change.
- `REF=<tag-or-commit>` selects the archive when running an already obtained
`install.sh` directly.
- `SOURCE_DIR=/path/to/seudesign/skills/sdp` installs a local tree without a
network download; this is the deterministic CI path.
- `FORCE=1` permits replacing an existing target that lacks seudesign's
ownership marker. Review that target first because the override is explicit.
- `LOCK_WAIT_SECONDS=30` sets the maximum lock wait in the `0..86400` second
range. A timeout
leaves the unverified existing lock untouched and reports its metadata paths
for operator inspection.
- `SIGKILL` and power loss cannot run shell traps. The installer therefore
leaves transaction/lock evidence and fails closed; confirm that no process
owns it and inspect `previous-sdp` before any manual restore or lock removal.
- `DOWNLOAD_CONNECT_TIMEOUT_SECONDS=10` and `DOWNLOAD_MAX_TIME_SECONDS=120`
bound the single remote archive attempt to `1..86400` seconds. It is not
retried automatically; inspect a failure and rerun explicitly.
The current immutable release is `v3.0.0`. Use that tag for a reproducible
release install, or a full commit SHA when the exact source identity must be
independent of a movable Git reference.
Package validation rejects development/version suffixes and binds installer
defaults and release notes to the stable manifest version.
Example local install:
```bash
SOURCE_DIR="$PWD/skills/sdp" DEST="$HOME/.agents/skills" sh install.sh
```
## What each installation contains
| Path | Installed components |
|---|---|
| Claude Code plugin | `sdp` skill plus the bundled `sdp-reviewer` Claude agent, constrained to read-only `Read`/`Grep`/`Glob` tools |
| Native Codex plugin | `sdp` skill and install-surface metadata using the existing logos; no app, MCP server, hook, or Claude-agent companion is declared |
| Gemini CLI extension | Repository context through `AGENTS.md`, which routes natural-language requests to `skills/sdp` |
| Generic installer | `skills/sdp` only; it does not install reviewer agents, manifests, evals, or repository tooling |
| Repository checkout | Full package, including AGENTS routing, examples, evals, validators, and installer tests |
## Package contents and counts
- Four on-demand workflow files: `design`, `review`, `interview`, and
`estimate`.
- [22 indexed case studies](skills/sdp/references/cases/index.md).
- 17 non-case guides: 12 topic references, four workflow files, and one
design-document template.
- Twelve independent eval suites covering scoped decisions, artifacts, partial
estimates, workflow sequences, review evidence, and interview behavior;
see [evals/README.md](evals/README.md) for execution and verification limits.
- A deterministic package validator and a staged, target-locked,
rollback-safe installer.
Run the local package gates with:
```bash
python3 scripts/validate_package.py .
python3 -m unittest discover -s tests -v
sh -n install.sh
sh -n tests/test_install.sh
dash -n install.sh
dash -n tests/test_install.sh
sh -n evals/review-evidence/scaffold.sh
sh -n evals/review-seeded-defect/scaffold.sh
INSTALLER_SHELL=sh sh tests/test_install.sh
INSTALLER_SHELL=dash dash tests/test_install.sh
claude plugin validate --strict .
gemini extensions validate .
git diff --check
```
Full sample outputs live in [examples/](examples/).
## Design philosophy
- **No premature scaling** — add infrastructure only after a bottleneck is
supported by workload estimates.
- **Every choice is a trade-off pair** — state what you gain and what you give
up.
- **No design without numbers** — begin with explicit assumptions and units.
Example invocations:
```text
Claude Code: /seudesign:sdp review
Codex: $sdp review
```