|
4 | 4 |
|
5 | 5 | This repository is used to create technical design documents using AI Agent mode in an IDE. When a user asks you to create a technical design document, follow the guidelines below. |
6 | 6 |
|
7 | | -> For a complete usage guide and workflow, see [`docs/agent-workflow.md`](../docs/agent-workflow.md). |
| 7 | +## Workflow |
8 | 8 |
|
9 | | -## Creating a New Technical Design Document |
| 9 | +### Trigger Conditions |
10 | 10 |
|
11 | | -### Step 1: Understand the Requirement |
| 11 | +Start this workflow when the user: |
| 12 | +- Asks to create a design document, tech spec, or technical design for a feature or module |
| 13 | +- Asks to update, revise, or add to an existing design document |
| 14 | +- Asks to create a schedule, Gantt chart, or milestone plan for a module |
| 15 | +- Asks to create a Protobuf model or service definition for a module |
| 16 | +- Asks to create a links file for a module |
12 | 17 |
|
13 | | -Ask clarifying questions if needed to understand: |
14 | | -- What feature or system is being designed? |
15 | | -- What problem does it solve? |
16 | | -- Who is the target audience for the document? |
17 | | -- Any specific constraints (tech stack, timeline, team size)? |
| 18 | +### Step 1: Clarify Requirements |
18 | 19 |
|
19 | | -### Step 2: Use the Template |
| 20 | +Before creating any files, ask the user for any missing information: |
| 21 | +- **Module name** (required): used as the folder name under `docs/`; must be kebab-case (e.g., `user-auth`, `notification-service`) |
| 22 | +- **What to create**: which files are needed (`links.md`, `tech-design.md`, `schedule.md`, `model.proto`) |
| 23 | +- **Feature description**: what the module does, the problem it solves |
| 24 | +- **Tech stack**: programming language, frameworks, databases, message queues |
| 25 | +- **Author / owner**: name to put in the document header |
| 26 | +- **Timeline**: start date, end date, key milestones (required only if creating `schedule.md`) |
| 27 | +- **External links**: Figma URL, Feishu doc URL, Slack channel, Jira epic (required only if creating `links.md`) |
20 | 28 |
|
21 | | -Always base new technical design documents on the template located at: |
22 | | -``` |
23 | | -templates/tech-design-template.md |
24 | | -``` |
25 | | - |
26 | | -### Step 3: Save the Document |
| 29 | +Do NOT create any files until you have at minimum: module name and feature description. |
27 | 30 |
|
28 | | -Create a dedicated folder for the module inside `docs/`. Each module folder may contain any combination of the following standardized files: |
| 31 | +### Step 2: Create the Module Folder |
29 | 32 |
|
| 33 | +All files for a module go into a dedicated folder: |
30 | 34 | ``` |
31 | | -docs/<feature-name>/ |
32 | | -├── links.md # External links (Feishu, Figma, Slack, Jira, etc.) |
33 | | -├── tech-design.md # Complete design document (split into parts if very long) |
34 | | -├── tech-design-part2.md # (optional) overflow section of the design doc |
35 | | -├── schedule.md # Gantt chart and milestone tracking |
36 | | -├── model.proto # Protocol Buffer model & service definitions |
37 | | -└── images/ # Architecture diagrams and other assets |
| 35 | +docs/<module-name>/ |
38 | 36 | ``` |
39 | 37 |
|
40 | | -Use the corresponding template from `templates/` for each file: |
41 | | -- External links → `templates/links-template.md` → save as `links.md` |
42 | | -- Design document → `templates/tech-design-template.md` → save as `tech-design.md` |
43 | | -- Schedule / Gantt → `templates/schedule-template.md` → save as `schedule.md` |
44 | | -- Data model → `templates/model-template.proto` → save as `model.proto` |
45 | | - |
46 | | -Only create the files that are relevant to the current module. Always create at least `tech-design.md`. |
47 | | - |
48 | | -### Step 4: Fill in the Content |
49 | | - |
50 | | -When generating the document, ensure that: |
51 | | -1. **All sections from the template are included** — do not skip sections; mark them as "N/A" if not applicable |
52 | | -2. **The overview is concise** — 2-3 sentences maximum |
53 | | -3. **Architecture diagrams** use ASCII art or reference image files stored in `docs/<feature-name>/images/` |
54 | | -4. **API designs** include request/response examples with realistic data |
55 | | -5. **Security considerations** are always addressed, even for internal tools |
56 | | -6. **Open questions** capture any unresolved decisions that need input from stakeholders |
57 | | -7. **links.md**: collect all Feishu, Figma, Slack, Jira, and other external references |
58 | | -8. **schedule.md**: use a Mermaid `gantt` block for the timeline; keep milestones in the table in sync |
59 | | -9. **model.proto**: follow proto3 syntax; define one service per module; use `google.protobuf.Timestamp` for time fields |
60 | | - |
61 | | -### Step 5: Update Status |
62 | | - |
63 | | -Set the document status to `Draft` initially. The user will update it to `In Review` or `Approved` as appropriate. |
64 | | - |
65 | | -## Document Quality Standards |
66 | | - |
67 | | -- Use clear, concise language |
68 | | -- Avoid jargon without explanation |
69 | | -- Use tables for structured comparisons |
70 | | -- Include diagrams for complex architectures (ASCII art is acceptable) |
71 | | -- Reference external standards or RFCs where applicable |
72 | | -- Ensure all links and cross-references are valid |
| 38 | +The folder name must be lowercase kebab-case. Never put module files directly in `docs/`. |
| 39 | + |
| 40 | +### Step 3: Create Files Using Templates |
| 41 | + |
| 42 | +For each file to create, copy the corresponding template and fill in the content: |
| 43 | + |
| 44 | +| File to create | Template to use | When to create | |
| 45 | +|----------------|-----------------|----------------| |
| 46 | +| `docs/<module-name>/links.md` | `templates/links-template.md` | When user provides external links (Figma, Feishu, Slack, Jira) | |
| 47 | +| `docs/<module-name>/tech-design.md` | `templates/tech-design-template.md` | Always — this is required for every module | |
| 48 | +| `docs/<module-name>/tech-design-part2.md` | `templates/tech-design-template.md` (sections only) | When `tech-design.md` exceeds ~500 lines; split overflow sections here | |
| 49 | +| `docs/<module-name>/schedule.md` | `templates/schedule-template.md` | When user provides timeline or asks for a schedule | |
| 50 | +| `docs/<module-name>/model.proto` | `templates/model-template.proto` | When the module has a data model or gRPC service to define | |
| 51 | + |
| 52 | +### Step 4: Fill In Each File |
| 53 | + |
| 54 | +#### links.md |
| 55 | +- Fill in the four rows: Figma, Feishu Doc, Slack channel, Jira epic |
| 56 | +- Use the exact URLs and channel names provided by the user |
| 57 | +- If the user did not provide a link for one of the four tools, leave it as `#` (placeholder) |
| 58 | +- Do not add rows for tools not in the template (no GitHub Issues, Linear, Confluence, Notion, etc.) |
| 59 | + |
| 60 | +#### tech-design.md |
| 61 | +- Fill in ALL sections from the template; mark sections as "N/A" if not applicable — do not remove them |
| 62 | +- **Status**: always set to `Draft` on creation |
| 63 | +- **Version**: always start at `1.0` |
| 64 | +- **Overview**: 2–3 sentences maximum; describe what the module does and the problem it solves |
| 65 | +- **Architecture diagrams**: use ASCII art inline; if the user provides an image file, reference it as `` |
| 66 | +- **API design**: include concrete request/response examples with realistic field values |
| 67 | +- **Security Considerations**: always fill in, even for internal-only tools; address at minimum: authentication, authorization, and data privacy |
| 68 | +- **Open Questions**: list any decisions that are unresolved or need stakeholder input |
| 69 | +- If the document becomes longer than ~500 lines, move the overflow sections (e.g., detailed API specs, data model) to `tech-design-part2.md` and add a cross-reference link |
| 70 | + |
| 71 | +#### schedule.md |
| 72 | +- Use a Mermaid `gantt` block with `dateFormat YYYY-MM-DD` |
| 73 | +- Group tasks into sections: Design, Development, Testing, Release |
| 74 | +- Keep the milestone table in sync with the Gantt chart entries |
| 75 | +- Mark completed milestones with `✅ Done`, in-progress with `🔄 In Progress`, pending with `⬜ Pending` |
| 76 | + |
| 77 | +#### model.proto |
| 78 | +- Use proto3 syntax |
| 79 | +- Package name follows `<org>.<domain>.<module>` pattern |
| 80 | +- Define exactly one `service` per proto file |
| 81 | +- Use `google.protobuf.Timestamp` for all timestamp fields |
| 82 | +- All enum values must have a `_UNSPECIFIED = 0` first entry |
| 83 | +- Include CRUD RPCs unless the user specifies otherwise: Create, Get, List, Update, Delete |
| 84 | + |
| 85 | +### Step 5: After Creating Files |
| 86 | + |
| 87 | +- Report which files were created and their paths |
| 88 | +- Ask the user to review the content and provide feedback |
| 89 | +- Do not change the `Status` field unless the user explicitly asks |
73 | 90 |
|
74 | 91 | ## Updating an Existing Document |
75 | 92 |
|
76 | | -When a user asks to update an existing tech design document: |
77 | | -1. Read the current document carefully |
78 | | -2. Make targeted updates to the relevant sections |
79 | | -3. Increment the version number (e.g., 1.0 → 1.1 for minor changes, 1.0 → 2.0 for major redesigns) |
80 | | -4. Add a note in the document about what changed if the status is `In Review` or `Approved` |
| 93 | +When the user asks to update a document: |
| 94 | +1. Read the current file content first |
| 95 | +2. Make the minimum changes required to address the request — do not rewrite unrelated sections |
| 96 | +3. Increment the version number: |
| 97 | + - Minor change (single section update, typo fix): `1.0 → 1.1` |
| 98 | + - Major change (new component, API redesign, scope change): `1.0 → 2.0` |
| 99 | +4. If the document status is `In Review` or `Approved`, add a brief change note at the top of the relevant section |
81 | 100 |
|
82 | | -## Example Prompts |
| 101 | +## Rules |
83 | 102 |
|
84 | | -Users may interact with you using prompts like: |
| 103 | +- **Never** create files outside the `docs/<module-name>/` folder structure |
| 104 | +- **Never** invent links or URLs — use placeholders (`#`) if the user has not provided them |
| 105 | +- **Always** use the templates in `templates/`; do not create files from scratch |
| 106 | +- **Always** create at least `tech-design.md` for any module |
| 107 | +- **Never** change the `Status` field autonomously; only change it when the user explicitly requests it |
| 108 | +- **Never** delete existing files unless the user explicitly asks |
| 109 | +- When splitting a long design doc, move content to `tech-design-part2.md` (not a new arbitrarily named file) and add a link between the parts |
85 | 110 |
|
86 | | -- "Create a tech design doc for a new notification service" |
87 | | -- "Write a technical design for migrating our database from MySQL to PostgreSQL" |
88 | | -- "Generate a design document for the search feature refactor" |
89 | | -- "Update the payment service tech design to add support for cryptocurrency" |
|
0 commit comments