{"name":"write-design-doc-prompt","description":"A prompt that writes a technical system design document before a big build - goals, context, a C4-style context and container view with Mermaid diagrams, options considered, the chosen design, security and data risks, and open questions with assumptions. Use when the user plans a new system or major feature, needs a design doc or RFC, or wants architecture written down.","category":"coding-prompts","tags":["architecture","docs","diagrams"],"models":["any"],"proven":false,"passing_families":0,"model_testing":"Not yet model-tested; testing Jan 2027","url":"https://theskillvault.ai/skills/write-design-doc-prompt","api_url":"https://theskillvault.ai/api/skills/write-design-doc-prompt","raw_url":"https://theskillvault.ai/api/skills/write-design-doc-prompt/raw","body":"# Write a design doc (prompt)\n\nA design doc gets the big decisions on paper before code: what you are building, how the parts fit, what you rejected and what could go wrong.\n\n## When to use\n- You are about to build a new service, integration or major feature.\n- Your team or a reviewer asked for a design doc or RFC.\n- You want the architecture written down so agents and teammates build the same thing.\n\n## When not to use\n- You need the product side (users, problems, features). Use write-prd-prompt first, then this.\n\n## Steps\n1. Write a short description of the system or feature, plus any constraints (budget, stack, deadline, team size).\n2. Paste it into the prompt below.\n3. Answer the questions it lists, then ask it to update the doc.\n4. Save it as `docs/design/name.md` and get a review before building.\n\n## Prompt\n```text\nWrite a technical design document for the system below. Team and context: {{TEAM SIZE, STACK, CONSTRAINTS}}.\n\nSections:\n1. Goals and non-goals: what this must achieve, and what it will not do.\n2. Business context: the priorities and the biggest business risks. A small startup can accept more risk than a large company; reflect our context.\n3. Security posture: existing controls, required controls (auth, secrets, data protection) and accepted risks.\n4. Design:\n   - Context view: a Mermaid diagram of the system, its users and outside systems, plus a table (name, type, description, responsibility).\n   - Container view: a Mermaid diagram of the main parts (apps, APIs, databases, queues) and how they talk, plus the same table.\n   - Key flows: one or two important flows step by step.\n5. Options considered: 2-3 alternatives and why the chosen design wins.\n6. Risks: what data we protect and how sensitive it is, what could fail, and how we would notice.\n7. Questions and assumptions: open questions, each with the default assumption you used.\n\nUse plain Markdown. Keep each section short; this is a working doc, not a report.\n\nSYSTEM:\n{{DESCRIPTION}}\n```\n\n## How to adapt\n- Small feature? Ask for sections 1, 4 (container view only), 5 and 7.\n- Need deployment detail? Add a deployment view diagram showing environments and hosting.\n\n## Gotchas\n- Do not paste real credentials, customer data or internal URLs into the description.\n- The AI fills gaps with assumptions. Read section 7 first and correct anything wrong.\n\n## Portability\nWorks with any stack and any chat AI. Mermaid diagrams render on GitHub, GitLab and most docs tools; no tool lock-in.\n\n## Done when\n- The doc covers goals, design views, options, risks and open questions.\n- The diagrams render and the open questions are answered or assigned.\n\n## Example prompt\n\"Write a design doc for adding team workspaces with roles and invites to my Next.js and Postgres app. Two developers, launch in six weeks.\"\n\n---\nConverted from the \"create_design_document\" pattern in danielmiessler/Fabric (MIT, Copyright (c) 2012-2024 Scott Chacon and others). See LICENSE.txt.","files":["LICENSE.txt"],"license":"MIT","license_name":"MIT License","license_url":"https://opensource.org/license/mit","attribution":"Based on work by Daniel Miessler and Fabric contributors (create_design_document pattern) (Copyright (c) 2012-2024 Scott Chacon and others, MIT License), https://github.com/danielmiessler/Fabric/blob/8ce0909d8622a61b6aaf539d467ba31bb7e0b6dd/data/patterns/create_design_document/system.md; adapted by TheSkillVault, https://theskillvault.ai","install":{"claude_code":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/raw' -o ~/'.claude/skills/write-design-doc-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/files/LICENSE.txt' -o ~/'.claude/skills/write-design-doc-prompt/LICENSE.txt'","cursor":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/raw' -o '.cursor/skills/write-design-doc-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/files/LICENSE.txt' -o '.cursor/skills/write-design-doc-prompt/LICENSE.txt'","agents":"curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/raw' -o '.agents/skills/write-design-doc-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-design-doc-prompt/files/LICENSE.txt' -o '.agents/skills/write-design-doc-prompt/LICENSE.txt'","mcp_url":"https://theskillvault.ai/mcp","cursor_mcp_deeplink":"cursor://anysphere.cursor-deeplink/mcp/install?name=theskillvault&config=eyJ1cmwiOiJodHRwczovL3RoZXNraWxsdmF1bHQuYWkvbWNwIn0%3D","mcp_config":{"mcpServers":{"theskillvault":{"url":"https://theskillvault.ai/mcp"}}}},"bundles":[],"tested_on":[{"family":"chatgpt","name":"ChatGPT","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"claude","name":"Claude","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"gemini","name":"Gemini","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"grok","name":"Grok","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"llama","name":"Llama","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"deepseek","name":"DeepSeek","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"mistral","name":"Mistral","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"qwen","name":"Qwen","outcome":null,"date":null,"source":null,"counts":false,"stale":false},{"family":"kimi","name":"Kimi K","outcome":null,"date":null,"source":null,"counts":false,"stale":false}],"proven_rule":{"threshold":5,"window_days":365,"computed_at":"2026-11-02T03:20:33.817Z"}}