technical-design
Skill0 starsChanged 4 months agoMITView on GitHub
Use when writing, revising, or reviewing a Technical Design Document (TDD) for a feature, epic, or set of user stories. Owns the technical design across backend/frontend/infrastructure and the decomposition of foundational work into `[Tech]` stories — grounded in existing codebase patterns and, when infra is in scope, live infrastructure state. Typically run after stories exist.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- ericwang200608-beep/LANYANT-Skillstheir own version, first seen Nov 8, 2026
- Lanqiao-Luca/ai-java-workflowtheir own version, first seen Nov 8, 2026
- thunderstormwang/AgentSkillstheir own version, first seen Nov 6, 2026
- willgt-oss/willgt-skillstheir own version, first seen Nov 1, 2026
- Garfield247/agent-skill-technical-designtheir own version, first seen Oct 13, 2026
- gener8v/gener8v.claude-skillstheir own version, first seen Sep 15, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- Lanqiao-Luca/ai-java-workflow★ 335same name
- gener8v/gener8v.claude-skills★ 3same name
- dirkkok101/skills★ 2same name
- ericwang200608-beep/LANYANT-Skills★ 2same name
- Garfield247/agent-skill-technical-design★ 0same name
- thunderstormwang/AgentSkills★ 0same name
- willgt-oss/willgt-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- checkpointSkill
- design-themeSkill
- dispatch-agentsSkill
- githubSkill
- github-templatesSkill
- gitSkill
- productSkill
- user-storiesSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 6 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Read CLAUDE.md (+ any role-scoped equivalent) before probing.
- Very specific: line 103
One node per component: Never gather multiple components in one box.
- Very specific: line 106
Interactions = labeled edges: Every component interaction is a flowchart edge labeled with the call/dispatch/render/consume it represents …
- Distinctive: line 114
Bullets/numbered over paragraphs: Never a multi-sentence paragraph where a list works.
- Very specific: line 121
Empty section = bare
None: No changes / inapplicable / out-of-scope → write exactly None. - Distinctive: line 195
Follow Canonical Sections order — never reorder.
- Distinctive: line 198
Follow Writing Style throughout the body — terse, arrows, bullets, deltas only, category-grouped notes.
- Distinctive: line 201
Never invent scope — run Discovery.
- Distinctive: line 202
Never decide product scope — surface as a blocker if missing.
- Very specific: line 203
Never add user-observable behaviour to [Tech] story ACs.
“Common” is measured: kept by at least 6 in 10 of the 5 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.
Files
Technical Design Expertise
Workflow
Resolve in-scope roles → probe each role's codebase → fold in design context if supplied (Design context) → run Discovery (answer from probe findings; unresolvable items become blockers) → surface blockers in one message before drafting → draft the canonical sections in order → decompose foundational work into [Tech] stories → validate against Constraints. For revisions, also classify scope impact (Scope Classification + Technical Stories Delta).
Inputs
| Parameter | Required | Notes |
sprint_goal | yes | From the requirement issue. |
stories | yes | [{id, title, user_story, acceptance_criteria, notes}] — in-scope user stories. Revisions add per-story implementation status. |
requirement_body | yes | Full requirement issue body. |
available_codebases | yes | [{name, role ∈ {backend, frontend, infrastructure}, path}]. |
design_context | no | Storybook surface stories — grounds frontend components + scope. placeholder blocks = out of scope (see Design context). |
feedback | no | Adjust-loop notes — create iterations only. |
existing_tdd_body | no | Prior TDD body. Present ⇒ revision mode → run Classification. |
change_intent | no | Feature-level scope delta (added/modified/removed). Revisions only; selects what to rewrite. |
existing_tdd_body + change_intent present ⇒ revision; else fresh authoring.
In-scope Resolution
| Role | In scope when stories or context imply… |
backend | persisted data, new API contract, new event, background job, auth/authz rule, server-side computation |
frontend | user-facing surface, page, component, interaction, client-side state/persistence |
infrastructure | new cloud resource, queue, cache, third-party integration, IaC module change, environment config |
A role not in scope → mark its sections None, do not omit.
Per-role Probe Briefs
Read CLAUDE.md (+ any role-scoped equivalent) before probing. The agent forms its own hypotheses and picks what to read — the table below is orientation, not a checklist. Probe until you can answer the Discovery categories for in-scope roles:
- Located closest existing analogue for each new component.
- Identified convention to follow or diverge from.
- Named where each new piece lives.
Unresolved item -> Discovery blocker. Don't probe indefinitely. Verify, don't assume: confirm each analogue/convention by reading the real file, never from memory of naming. Infrastructure in scope → per resource, call the cloud/platform API for actual current state (running/stopped, attached/detached, exists/missing, rule present/absent) — don't infer it from IaC source. Can't confirm via tooling → Discovery blocker.
| Role | Starting points |
backend | Existing entities, models, DB tables; command/query handlers, services, repositories; API controllers/routes; auth/authz patterns. Record file paths, names, conventions, gaps. |
frontend | Existing pages, routes, feature folders; components; API client calls/hooks; state slices/query keys. Shared primitives/components/tokens — exist or closest analogue. Record file paths, names, conventions, gaps. |
infrastructure | Existing modules/resources for the implied capability; config to extend. Record resource names, types, conventions, gaps, plus live-state findings (actual deployed state, not IaC-assumed). |
Design context
Caller-supplied design context (Storybook surface stories) grounds frontend component + scope decisions.
placeholder blocks within stories = existing areas the sprint doesn't change (artifacts from ui-design agent, not new scope). Ignore them -> derive no components, data models, API surface, or [Tech] stories from placeholder regions. Design only the changed/new areas.
Discovery Categories
Answer from codebase context first; only unresolvable items become blockers. When surfacing a blocker, state what you inferred -> targeted answer.
| Category | Decisions |
| Data ownership | New table vs extend? Which service/DB owns? Shared? |
| Auth & authorisation | Roles/permissions? Resource or role level? |
| API surface | New endpoints or extend? REST or event-driven? Versioning? |
| Integration boundaries | External services? Contract ownership? |
| NFRs | Latency/throughput targets? Data volume? SLA? |
| Real-time vs async | Live updates, webhooks, polling, batch? |
| Migration & compatibility | Data to migrate? Destructive schema? Backward compat? Confirm current live schema/state before designing the migration. |
| Infrastructure constraints | Cloud/region/cost limits? Ground against live infra state, not IaC-assumed. |
| Rollout | Feature flag? Gradual? Rollback trigger? |
| Cross-team | Blocking/blocked? Shared contracts? |
Canonical Sections
Cover every area in this order. Write None where inapplicable — nothing else, no reason or explanation. Every diagram = Mermaid in a fenced ```mermaid block — never ASCII art. flowchart for structure/components, sequenceDiagram for flows.
| # | Field | Define |
| 1 | high_level_diagram | Services, databases, caches, third-party — label new vs existing. Mermaid flowchart. |
| 2 | data_models | Entities, relationships, indexes — ERD or schema |
| 3 | api_spec | Method, route, auth, request/response, status codes |
| 4 | event_schemas | Topic, structure, producer, consumer — or None |
| 5 | happy_path | Mermaid sequenceDiagram. Participants must be high-level system modules only: actors (e.g. Customer, Admin) and major system boundaries (e.g. Web, API, Database, External Service). Omit all implementation details — internal libraries, state managers, hooks, query clients, and sub-components must not appear as participants. |
| 6 | unhappy_path | Key failure scenario and system response. Mermaid sequenceDiagram. |
| 7 | components_design | Backend + Frontend sub-sections. High-level actors only (e.g. endpoint, validator, handler, specification, repository; page, UI sub-component, API client, model layer), tagged [NEW]/[MODIFIED]/[RENAMED]/existing. Diagram = Mermaid flowchart — see Components Design Diagram Rules below. Design decisions (contracts, ordering guarantees, where a responsibility lives) go as terse notes grouped under labeled sub-headings by category (e.g. **Webhook**, **Reads & projections**) — never one flat bullet list. |
| 8 | infrastructure_design | Cloud resources added/modified; IaC changes. None if unchanged — bare, no explanation. |
| 9 | tech_stack | New languages/frameworks/libraries/infra only |
| 10 | security | Auth, authz, encryption at rest and in transit |
| 11 | scalability | Throughput/latency targets, query design, caching, async |
| 12 | failure_modes | Min 2 rows: Scenario, Impact, Mitigation |
| 13 | migration | Data migration, cutover, rollback. Per migration in apply order: fenced ```sql Up (cutover) + Down (rollback) scripts. Or None |
| 14 | monitoring | Key metrics, alert thresholds |
| 15 | technical_stories | Table: Title, Scope, Required by, Key ACs |
Components Design Diagram Rules
Backend + Frontend each render as a Mermaid flowchart TD. Rules:
- One node per component. Never gather multiple components in one box. Each endpoint/handler/port/impl/hub, each page/hook/transport-module/leaf-component = its own node.
- Architecture order via
subgraphlayers. Group nodes by layer, ordered by the stack's dependency direction — backendDomain → Application → Infrastructure / Api; frontendShell → Hooks → Transport → Components. Onesubgraphper layer. - Location is the only node metadata. Node label =
<b>name</b>+ tag ([NEW]/[MODIFIED]/[RENAMED]/[existing]) +loc:file path. No responsibility prose, no method signatures, members, validation rules, query keys, hooks/state wiring inside the node — behaviour lives on the edges + the category notes. - Interactions = labeled edges. Every component interaction is a
flowchartedge labeled with the call/dispatch/render/consume it represents (e.g.OrderCreatedEvent,NotifyOrderPlacedAsync,renders,subscribes via). Port→impl = dotted edge (-.implemented by.->). - Verify
loc:against the real file. Path must point at the actual file (existing) or its planned path (new) — never guessed.
Writing Style
Governs the <body> markdown. Terse, direct, scannable.
- Cut filler + articles. Drop words carrying no info ("the", "a", "simply", "in order to", "is responsible for", "note that"). Fewest words per idea.
- Bullets/numbered over paragraphs. Never a multi-sentence paragraph where a list works. One fact per bullet.
- Arrows for transitions.
→for state moves, flows, routing, mappings (Pending → Processing,handler → repo → table,write → IOrderRepository). Not prose ("transitions to", "is passed to", "which then calls"). - Describe deltas only. Explain what's
[NEW]/[MODIFIED]. Don't explain or re-justify unchanged behaviour — reference it in one phrase and move on. No "X stays the same because…". - No hand-holding. Cut restated context, obvious-step narration, and parentheticals that paraphrase the prior clause.
- Group notes by category under bold sub-headings, not one flat list (see Components Design).
- Tables for contracts/schemas/failure modes; Mermaid for diagrams.
- State once. A locked decision stated up front is referenced later, never re-explained.
- Empty section = bare
None. No changes / inapplicable / out-of-scope → write exactlyNone. No reason, no "what's reused" bullets, no justification.
Technical Story Decomposition
Emit one [Tech] story per discrete piece of foundational work satisfying all:
- Enables user stories but not user-observable on its own.
- Developer-verifiable completion condition (build passes, migration runs, primitive matches contract, endpoint returns documented shape).
- Can't split further into independently-shippable items.
Qualifies: shared component/design primitive, schema migration, IaC module, auth middleware, new event topic + producer scaffold, shared API client. Doesn't qualify (fold into owning user story): single endpoint for one story, single page's local state, copy changes, one-off validation rules.
[Tech] ACs developer-verifiable only — never user-observable. Link dependent user stories via required_by_titles.
Classification (revisions only)
Revisions emit two tables — one per user story, one per [Tech] story.
Scope Classification (per user story)
Compare the revised TDD against each user story (ignore [Tech] stories).
| Classification | Condition | Action |
additive | Adds new behaviour; existing implementation remains valid | Flag for incremental work; no rework |
breaking | Conflicts with existing implementation | Surface affected files/endpoints; caller decides regenerate vs migrate |
structural | Requires full revisit; treat affected files as blank slate | List affected files; recommend story regeneration |
unaffected | Story not touched | Note and move on |
Technical Stories Delta (per [Tech])
Match each [Tech] by title against the baseline TDD's technical_stories table.
| Action | Condition |
added | New [Tech] work the baseline TDD lacked. |
modified | Existing [Tech] story whose scope/ACs changed. |
removed | Baseline [Tech] story no longer required. |
unchanged | Baseline [Tech] story still valid as-is. |
Technical-story Spec
- title: "[Tech] <work item>"
scope_summary: "<one sentence>"
acceptance_criteria:
- "<developer-verifiable AC>"
notes:
edge_cases: ["<text>", ...]
references: [{label: "<text>", url: "<url>"}, ...]
depends_on_titles: ["<title>", ...]
required_by_titles: ["<user-story title>", ...]Returns
$TDD_RESULT:
<tdd>
<body><!-- full TDD markdown — canonical sections 1–15 in order, present tense --></body>
<technical_stories><!-- list of [Tech] specs per Technical-story Spec --></technical_stories>
<scope_classification><!-- revisions only: Scope Classification table --></scope_classification>
<technical_stories_delta><!-- revisions only: Technical Stories Delta table --></technical_stories_delta>
</tdd><body>+<technical_stories>always present.<scope_classification>+<technical_stories_delta>present only whenexisting_tdd_bodysupplied; omit on fresh authoring.<body>= clean current-state snapshot, never a diff (see Constraints).
Constraints
- Follow Canonical Sections order — never reorder.
- Make risks + trade-offs explicit. Rejected an alternative under the current design -> say why in one line. Never narrate a prior version's approach as a rejected alternative.
- Revised TDD = clean snapshot of the current target design, never a diff against a prior version. Every section in present tense. No change-narration ("previously/now/changed from", "no longer references", "New in this revision", changelog prose), no superseded/prior-version decisions carried forward. Old-code removal =
[Tech]story scope, not a design section. Distinct from the codebase-relative[NEW]/[MODIFIED]/existing actor tags in Components Design — those stay. - Follow Writing Style throughout the body — terse, arrows, bullets, deltas only, category-grouped notes.
- Components Design at actor level only — high-level actors + interconnections via Mermaid
flowchartedges (one node per component,loc:file path the only node metadata; see Components Design Diagram Rules). Implementation specifics (signatures, members, query keys, state wiring) never appear anywhere in the TDD. - Ground every decision in codebase context — cite file paths, existing components, conventions. Justify any divergence.
- Never invent scope — run Discovery; do not assume product behaviour the caller hasn't specified.
- Never decide product scope — surface as a blocker if missing.
- Never add user-observable behaviour to
[Tech]story ACs.
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
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.

