personal-tech-design

Personal Tech Design — Technical Design Document Generator (Personal)

Help the user write a structured technical design document following a standard template, then save it to their personal Yuque knowledge base.

When to Use

• User wants to write a technical design document or RFC and save it to their personal repo
• User says "help me write a technical proposal", "write a tech design", "I want to write a design doc"
• User describes a feature/system and needs it formalized into a design doc for personal reference

Required MCP Tools

All tools are from the yuque-mcp server:

• yuque_search — (Optional) Search for related existing docs for context
• yuque_list_repos — Find the target personal knowledge base
• yuque_create_doc — Create the design document

Reference

The full template is in references/template.md. Load it when generating the document.

Workflow

Step 1: Understand the Requirements

Gather from the user:

Field	Required	Description
Project/Feature Name	Yes	What is being designed
Background and Problem	Yes	Why this is needed, what problem it solves
Goals	Yes	What success looks like
Constraints	No	Technical constraints, timeline, budget
Existing Solutions	No	Any existing approaches or prior art

If the user provides a brief description, ask clarifying questions:

• "What problem does this feature solve?"
• "Are there any technical constraints? For example, must a certain framework be used, or must it be compatible with the existing system?"
• "What is the expected timeline?"

Step 2: (Optional) Search for Context

If relevant, search Yuque for related existing documents:

Tool: yuque_search
Parameters:
  query: "<related keywords>"
  type: "doc"

This helps:

• Avoid duplicating existing designs
• Reference prior decisions
• Understand the current architecture

Step 3: Generate the Design Document

Load the template from references/template.md and fill in each section based on the user's input and your technical analysis.

Key sections to fill:

1. Background — Problem statement, current situation
2. Goals — What this design achieves, non-goals
3. Design — The core technical approach
   • Architecture diagram description (describe in text/ASCII if needed)
   • Core components and their responsibilities
   • Data model / API design
   • Key flows (sequence of operations)
4. Tech Stack — Why specific technologies were chosen
5. Alternatives — Other approaches considered and why they were rejected
6. Timeline — Milestones and estimated effort
7. Risks — What could go wrong and mitigation strategies
8. References — Related docs, links, prior art

Step 4: Review with User

Present the draft to the user before saving. Ask:

• "Is the proposal content accurate? Is there anything that needs adjustment?"
• "Do you want to add any other technical details?"

Step 5: Save to Personal Yuque

Tool: yuque_list_repos
Parameters:
  type: "user"

Find or ask for the target personal repo (often "technical proposal" or "design doc" or "notes").

Tool: yuque_create_doc
Parameters:
  repo_id: "<namespace>"    # e.g., "username/tech-docs"
  title: "[技术方案] <项目名称>"
  body: "<formatted design document>"
  format: "markdown"

Step 6: Confirm

✅ 技术方案已创建（草稿状态）！

📄 **[[技术方案] 项目名称](文档链接)**
📚 已保存到：「个人知识库名称」

### 文档结构
- 背景与目标
- 方案设计（含 X 个核心模块）
- 技术选型对比
- 排期（预计 X 周）
- 风险评估（X 个风险点）

💡 文档为草稿状态，可随时编辑完善。

Guidelines

• Write the design doc in Chinese (default) unless the user specifies English
• Be specific in the design section — include data models, API signatures, flow descriptions
• For tech stack comparison, use a table with pros/cons
• Keep the document actionable — someone should be able to implement from this doc
• If the user's requirements are vague, make reasonable assumptions and note them clearly with "【Assumption】" markers
• Don't over-engineer — match the design complexity to the project scope
• This skill saves to personal repos — for team repos, use team-tech-design

Error Handling

Situation	Action
User provides very vague requirements	Ask 2-3 targeted questions before generating
yuque_search finds conflicting existing designs	Mention them and ask user how to reconcile
yuque_create_doc fails	Show error, offer to output the markdown for manual copy
User wants to update an existing design doc	Use yuque_search to find it, then suggest creating a v2 or appendix
User wants to save to team repo	Suggest using team-tech-design skill instead