Các trường hợp sử dụng quy trình AI (AI Workflow Use Cases)
Ngữ cảnh: Bạn đang làm dự án FE viết note, giống như Notion
7 kịch bản: 5 kịch bản dùng bộ skill /morkit:*, cộng 2 kịch bản dựng UI từ Figma (qua Figma MCP hoặc file HTML tự export). Thể hiện rõ từng bước phía dưới, kèm output dự kiến của AI. Mỗi Use Case (UC) được chia thành các bước (step) có Tại sao · Bạn làm
· Bạn thấy, để người mới follow được.
Dùng sidebar bên trái chuyển UC, hoặc click vào từng bước (step) để chuyển hướng nhanh.
Brownfield onboarding — quét codebase có sẵn thành bộ docs tối ưu cho AI
Tình huống thực tế: bạn vừa được giao một repo brownfield (đã có
code, có thể có vài tài liệu rời rạc như README) nhưng chưa có bộ docs/
có cấu trúc cho AI agent. UC này dùng /morkit:init
để quét codebase một lần và dựng taxonomy 00-overview … 90-operations,
rồi duy trì bằng /morkit:docs update. Demo trên repo
Notion-clone (Next.js 15 · TipTap · Drizzle · Supabase).
Hoàn toàn LLM-driven — không Python, không venv, không cài gì thêm. init tự nhận biết đây là brownfield (có manifest + có code) rồi chạy pipeline scout. Người mới nên chú ý Step 3 (cổng duyệt docs-plan) — đây là chỗ chốt phạm vi trước khi sinh tài liệu.
Step 1 Gõ /morkit:init — preflight + chọn scale
— Stage 0: kiểm tra docs/ · tự phát hiện brownfield (có manifest + có code) · hỏi project hay per-module
# ─ Tại sao bước này? ──────────────────────────────────────
# init là bootstrap docs LẦN ĐẦU, chạy 1 lần cho mỗi dự án.
# Không cần gom input, không cài venv — chỉ gõ lệnh ngay trong
# repo. Stage 0 lo phần "định hướng": docs/ đã có chưa, đây là
# brownfield hay greenfield, taxonomy ở mức project hay module.
# ──────────────────────────────────────────────────────────
▶ Bạn làm/morkit:init
$ /morkit:init
# tuỳ chọn: /morkit:init ../another-service · --scope project|module · --yes · --agents
▼ Bạn thấy — Stage 0 (Preflight & Scope)
[preflight] docs/ tại target... trống → tiếp tục init
// nếu đã có 00-overview/ → STOP, bảo dùng /morkit:docs update
[detect] manifest: package.json ✓
source LOC: ~6.2k ✓ có code
→ BROWNFIELD (chạy pipeline scout, Stages 1–6)
▼ Cổng #1 — chọn scale (AskUserQuestion) // bỏ qua nếu truyền --scope
┌─ Taxonomy ở mức nào? ────────────────────────────────────┐
│ (•) project — một cây docs/ cho cả repo │
│ ( ) module — mỗi module một taxonomy (hợp monorepo) │
└──────────────────────────────────────────────────────────┘
// gợi ý monorepo nếu thấy pnpm-workspace.yaml / packages/* / apps/*
Step 2 Scout codebase (read-only, song song) — Stage 1 — dispatch agent morkit-native · bỏ qua .git/node_modules/dist · gom tín hiệu → ánh xạ folder điều kiện
# ─ Tại sao bước này? ──────────────────────────────────────
# Docs phải bám vào CODE THẬT (không bịa). Scout đọc-only quét
# repo song song để biết có gì: stack, route, model, UI, test,
# CI. Tín hiệu tìm được quyết định folder nào được tạo — không
# có component thì không tạo folder (no empty folders).
# ──────────────────────────────────────────────────────────
▼ Bạn thấy (scout log)
[scan] cây thư mục + LOC theo ngôn ngữ · entry points
stack (từ manifest): Next 15 · React 19 · Drizzle · Supabase
14 route · 8 ORM model · 6 trang UI · Vitest · ESLint + commitlint · CI
[map] tín hiệu → folder điều kiện (theo taxonomy):
schema/migrations → 20-design/20-data/DATA-MAP
routes/handlers → 20-design/30-api/API-MAP
UI components → 20-design/40-ui/UI-MAP
lint/commit config → 40-ai-coding/CODE-STANDARDS
manifest → 00-overview/STACK
# Scout CHƯA ghi gì ra docs/. Nó chỉ thu thập để dựng docs-plan
# cho bạn duyệt ở Step 3.
Step 3 🚦 Cổng duyệt docs-plan (Stage 2 — gate quan trọng) — xem folders/files sẽ tạo + danh sách feature tạm + scale · chọn Proceed / Adjust / Abort
# ─ Tại sao bước này QUAN TRỌNG? ───────────────────────────
# Đây là chỗ chốt PHẠM VI trước khi sinh tài liệu. Bạn xem
# trước folder/file nào sẽ tạo (core + folder điều kiện scout
# tìm được) và bỏ bớt phần không cần. Sửa ở đây = đổi 1 lựa
# chọn; sửa sau khi đã sinh = xoá/viết lại nhiều file.
# ──────────────────────────────────────────────────────────
▼ Cổng #2 — docs-plan (AskUserQuestion)
Sẽ tạo (scale = project):
00-overview/ SCOPE · STACK · GLOSSARY · DEPENDENCY-MAP (+ MAP ở Step 4)
10-requirements/ FEATURE-LIST (18 FR tạm) + flows
20-design/ ARCHITECTURE · INVARIANTS · *-SYS-SPEC · DATA/API/UI-MAP
30-test/ TEST-STRATEGY · TEST-RUNBOOK · TEST-MATRIX
40-ai-coding/ CODE-STANDARDS · KNOWN-PITFALLS · RISK-REGISTER · …
→ Bạn chọn?
(•) Proceed — sinh đúng plan này
( ) Adjust — chọn lại folders / đổi scale
( ) Abort — huỷ
# Chọn Proceed → sang Step 4. (Truyền --yes để bỏ cổng này.)
Step 4 Sinh nội dung → mỏ neo (Stage 3–4: Scout→Content→MAP) — dispatch song song theo nhóm, file ownership tách biệt · viết content TRƯỚC, MAP SAU
# ─ Tại sao thứ tự Content TRƯỚC, MAP SAU? ─────────────────
# MAP/anchor là index trỏ tới file thật. Phải có content trước
# thì link trong MAP mới resolve được (không broken link). Mỗi
# nhóm do 1 agent ghi, ownership tách biệt → không đụng file nhau.
# ──────────────────────────────────────────────────────────
▼ Stage 3 — Content (song song)
┌─ 10-requirements/ FEATURE-LIST (18 FR) + flows FR-NNN-* ─┐
├─ 20-design/ ARCHITECTURE · INVARIANTS · SYS-SPEC ├─▶ song song
├─ 30-test/ TEST-STRATEGY · RUNBOOK · MATRIX │
├─ 40-ai-coding/ CODE-STANDARDS · PITFALLS · RISK │
└─ 00-overview/ SCOPE · STACK · GLOSSARY · DEP-MAP ─┘
▼ Stage 4 — Anchors (sau khi content xong)
A 00-overview/SOURCE-MAP.md concern → file → symbol
A 00-overview/DOCUMENT-MAP.md vai trò folder + read paths
A 20-design/DESIGN-MAP.md · 40-ai-coding/AI-CODING-GUIDE.md
A README (root mỏng + per-folder)
# Mỗi file ~100 LOC, front-matter source_files (nơi suy từ code),
# cross-link tới file thật. >800 LOC → tách.
Step 5 🚦 Con trỏ CLAUDE.md/AGENTS.md + validate (Stage 4b–5)
— ghi pointer block qua marker + approve gate mỗi file · validate links/front-matter/traceability
# ─ Tại sao bước này? ──────────────────────────────────────
# Harness tự nạp CLAUDE.md (Claude Code) / AGENTS.md (Codex).
# init ghi 1 pointer block trỏ vào DOCUMENT-MAP để agent biết
# vào docs/ ở đâu. Chỉ đụng phần trong marker, KHÔNG động nội
# dung khác — và phải bạn duyệt từng file.
# ──────────────────────────────────────────────────────────
▼ Cổng — approve pointer block (mỗi file 1 lần)
┌─ CLAUDE.md (root) ───────────────────────────────────────┐
│ <!-- morkit:docs --> │
│ Đọc docs/00-overview/DOCUMENT-MAP.md để định hướng. │
│ <!-- /morkit:docs --> │
└──────────────────────────────────────────────────────────┘
[A] tạo mới · [B] nối cuối · [C] thay trong marker → duyệt
// --agents hoặc phát hiện Codex → ghi thêm AGENTS.md
▼ Stage 5 — Validate
Kích thước file (~100 LOC, >800 → tách) ✓
Cross-links resolve (kể cả link CLAUDE.md) ✓ 0 broken
Front-matter source_files trên doc suy từ code ✓
Traceability FR/NFR/INV · TEST-MATRIX.Ref ✓
✅ docs/ sẵn sàng — báo cáo: đã tạo gì · gaps · file quá khổ
// có docs cũ dạng phẳng? Stage 6 hỏi absorb / để cạnh / bỏ qua.
Step 6 Bảo trì khi code đổi: /morkit:docs update
— dò drift theo source_files · re-scout vùng đổi · bridge change-spec · giữ phần sửa tay
# ─ Tại sao KHÔNG chạy lại /morkit:init? ───────────────────
# init là bootstrap 1 lần. Khi code đổi, dùng /morkit:docs
# update: nó dò doc nào lệch (qua front-matter source_files),
# chỉ re-scout vùng đổi, và GIỮ phần bạn sửa tay — không ghi đè
# cả bộ. (Không có "diff engine" Python — toàn bộ LLM-driven.)
# ──────────────────────────────────────────────────────────
▶ Bạn làm
$ /morkit:docs update
# hoặc: /morkit:docs update --yes · /morkit:docs summarize (refresh nhanh SOURCE-MAP + DOCUMENT-MAP)
▼ Bạn thấy
[drift] doc lệch since `updated` (theo source_files):
M 20-design/30-api/API-MAP src/app/api/** đổi
M 10-requirements/FEATURE-LIST FR-004 thêm
[bridge] gấp change-spec đang active vào docs (WHAT/WHY):
proposal/design/tasks → FEATURE-LIST · ADR · TEST-MATRIX
// code = HOW (canonical) · spec = WHAT/WHY · spec lệch code → status: drift
[write] cập nhật content → re-derive MAP · bump `updated`
✓ phần sửa tay ngoài vùng regenerate được giữ nguyên
# Mẹo: chạy /morkit:docs update TRƯỚC /morkit:archive để WHAT/WHY
# của change kịp vào docs/ trước khi change bị archive.
#
# docs/ giờ là input chất lượng cho: UC3 (feature) · UC4 (fix) · UC5 (review).
Greenfield project — từ ý tưởng đến docs lớn dần cùng code
Tình huống thực tế: bạn được giao một dự án greenfield — chưa có
code, chưa có docs, chỉ có idea note / requirement. Khác brownfield, ở đây
/morkit:init KHÔNG quét được gì để suy ra docs:
nó chỉ gieo một khung docs đúng định dạng (no fiction), rồi
/morkit:docs update bồi dần phần suy-từ-code khi bạn
viết code. UC này là quy trình end-to-end cho TaskFlow, mọi bước bám lệnh có thật.
Khác UC1 thế nào? Brownfield có code làm anchor → init quét ra docs đầy
đủ ngay. Greenfield không có anchor → init chỉ gieo SPINE (SCOPE · DOCUMENT-MAP
· FEATURE-LIST rỗng · con trỏ CLAUDE.md). WHAT/WHY nắm qua
/morkit:propose; docs code-derived (SOURCE-MAP, SYS-SPEC,
DATA/API/UI-MAP) do /morkit:docs update tạo dần khi có code.
Step 1 Brainstorm ý tưởng với /morkit:brainstorming
— explore stance · thinking partner free-form, không viết code · auto-save design log cuối phiên
# ─ Tại sao bước này? ──────────────────────────────────────
# Greenfield bắt đầu từ 0, không có code/docs làm anchor. Trước
# khi gieo docs, làm rõ vision/scope đã. Brainstorming ở "explore
# stance": mở thread, vẽ ASCII diagram, KHÔNG viết code — cuối
# phiên tự lưu design log để feed các bước sau.
# ──────────────────────────────────────────────────────────
▶ Bạn làm/morkit:brainstorming
$ /morkit:brainstorming
TaskFlow: trình quản lý công việc cho team nhỏ. Giúp tôi shape scope.
▼ Bạn thấy (explore stance)
▸ Hỏi câu mở thread thay vì checklist:
"Cho IC độc lập hay cho team? Khác biệt này quyết định data model,
billing, SSO…"
▸ Vẽ ASCII diagram khi cần (so sánh approach, state machine, data flow)
▸ Surface risks & unknowns: "OTP email tốn $ → Magic Link như Notion?"
▸ Khi đủ shape → confirm rồi auto-save design log:
morkit/output/specs/2026-05-27-taskflow-design.md
# design log: problem · approaches · decisions · open questions · next step
# → là ngữ cảnh cho /morkit:propose (Step 4) và để bạn viết SCOPE ở Step 2.
Step 2 /morkit:init — gieo khung docs rỗng (Stage 1G)
— init tự phát hiện greenfield (không manifest + ~0 LOC) · gieo SPINE đúng định dạng · TUYỆT ĐỐI không bịa
# ─ Tại sao init không sinh SRS/HLD ở đây? ─────────────────
# Chưa có code thì không có gì để "suy ra" — bịa feature/kiến
# trúc/nguồn là sai (no fiction). Nên greenfield chỉ gieo SPINE
# đúng định dạng để vừa code vừa bồi. Docs code-derived để dành
# cho /morkit:docs update khi code đã có.
# ──────────────────────────────────────────────────────────
▶ Bạn làm/morkit:init
$ /morkit:init
▼ Bạn thấy — Stage 0 phát hiện greenfield
[detect] manifest (package.json/pyproject/go.mod…) không có
source LOC (trừ README/LICENSE/dotfiles) ~0
→ GREENFIELD → Stage 1G (bỏ scout)
▼ Gieo SPINE (chỉ những file này)
A docs/00-overview/SCOPE.md status: draft (hỏi 1–2 câu In/Out scope)
A docs/00-overview/DOCUMENT-MAP.md chỉ liệt kê folder đã gieo
A docs/10-requirements/FEATURE-LIST.md bảng RỖNG (Legend + header, sẵn cho FR-001)
A CLAUDE.md (root) con trỏ → DOCUMENT-MAP (qua approve gate)
# BỎ QUA (update bồi sau): SOURCE-MAP · SYS-SPEC · TEST-* ·
# CODE-STANDARDS · DATA/API/UI-MAP — vì chưa có code.
Step 3 🚦 Opt-in: gieo STACK + ARCHITECTURE dự kiến?
— một cổng duy nhất · mặc định KHÔNG (--yes cũng = KHÔNG) · đây là intent, không phải code-derived
# ─ Tại sao tách riêng + mặc định KHÔNG? ───────────────────
# STACK/ARCHITECTURE là dự kiến (intent), CÓ THỂ lệch code về
# sau. Nên chỉ gieo khi bạn chủ động chọn, và đánh dấu bằng
# status để /morkit:docs update đối chiếu lại với code thật.
# ──────────────────────────────────────────────────────────
▼ Cổng (AskUserQuestion · default NO)
Cũng gieo STACK + ARCHITECTURE dự kiến (forward-looking)?
( ) Có → tạo 2 file intent:
00-overview/STACK.md status: draft (bỏ source_files)
20-design/00-core/ARCHITECTURE.md status: planned
(•) Không (mặc định) — để update dựng từ code thật sau
# status: planned/draft đánh dấu "intent gieo trước code". --yes
# → tự chọn Không. Sau Stage 1G: ghi con trỏ CLAUDE.md + validate
# rút gọn (link resolve, front-matter) → báo cáo "đã gieo gì +
# chạy /morkit:docs update khi có code".
Step 4 Viết spec cho từng thay đổi: /morkit:propose → /morkit:review
— nắm WHAT/WHY trước khi code · sinh proposal · design · tasks (TDD) · review-checklist
# ─ Tại sao bước này? ──────────────────────────────────────
# FEATURE-LIST đang rỗng. Thay vì bịa, ta nắm WHAT/WHY của từng
# thay đổi qua /morkit:propose — sinh proposal (lý do) + design
# (cách làm) + tasks (TDD). /morkit:docs update sẽ "bridge" các
# spec này vào docs/ ở Step 6.
# ──────────────────────────────────────────────────────────
▶ Bạn làm/morkit:propose
$ /morkit:propose Email signup + OTP verify cho TaskFlow
$ /morkit:review # sinh checklist; ghi "Overall Decision: OK" để mở khoá thực thi
▼ Bạn thấy — morkit/output/spec/email-signup-otp/
A proposal.md Why + Capabilities ("What changes")
A design.md Decisions · Risks · Tech Stack · Non-Goals
A tasks.md chia bước theo TDD (write failing test trước)
A review-checklist.md PENDING → bạn duyệt OK
# Lặp /morkit:propose cho mỗi capability (Epic-Auth, Epic-Tasks…).
Step 5 Code theo plan — executing-plans / TDD
— bị plan-review-gate chặn tới khi checklist OK · viết test trước, code sau · giờ repo MỚI có code
# ─ Tại sao bước này? ──────────────────────────────────────
# Có spec OK rồi thì build. Sau bước này repo greenfield bắt đầu
# CÓ code thật (manifest, route, model, test) — chính là thứ
# /morkit:docs update cần để dựng docs code-derived ở Step 6.
# ──────────────────────────────────────────────────────────
▶ Bạn làm
$ /morkit:execute-plan # hoặc skill executing-plans / subagent-driven-development
▼ Bạn thấy
test-driven-development: Red → Green → Refactor (test fail trước)
A package.json · src/app/api/auth/** · drizzle schema · *.test.ts
✓ tests pass · checklist "Overall Decision: OK" đã mở khoá thực thi
# Repo giờ KHÔNG còn rỗng → đủ điều kiện để update suy ra docs.
Step 6 /morkit:docs update — bồi docs khi code lớn dần
— "new components" tạo folder điều kiện · bridge change-spec · dựng SOURCE-MAP/SYS-SPEC/DATA·API·UI-MAP
# ─ Tại sao dùng update, không init lại? ───────────────────
# init đã chạy 1 lần (gieo spine). Khi code xuất hiện, update lo
# phần còn lại: scout vùng mới → bước "new components" tạo folder
# điều kiện (vd thêm DB → 20-data) + dựng docs code-derived, đồng
# thời bridge các change-spec (Step 4) vào docs.
# ──────────────────────────────────────────────────────────
▶ Bạn làm
$ /morkit:docs update
▼ Bạn thấy
[new] scout thấy component chưa có folder → tạo:
A 20-design/30-api/API-MAP · 20-design/20-data/DATA-MAP
A 00-overview/SOURCE-MAP · 20-design/.../*-SYS-SPEC · 30-test/TEST-MATRIX
[bridge] change-spec active (tasks đã tick hết, chưa archive):
proposal/design/tasks → FEATURE-LIST (FR-001 Email signup) · ADR · TEST-MATRIX
✓ FEATURE-LIST rỗng lúc đầu giờ có FR thật, suy từ spec + code
// spec khẳng định nhưng chưa thấy trong code → status: drift (vào báo cáo)
[stack] STACK/ARCHITECTURE (nếu đã gieo ở Step 3) đối chiếu lại code thật
# Lặp theo mỗi đợt build: code lớn tới đâu, docs/ bồi tới đó.
Step 7 🚦 Chạy /morkit:docs update TRƯỚC /morkit:archive
— archive xong thì change ra khỏi tầm bridge · WHAT/WHY sẽ không kịp vào docs/
# ─ Tại sao thứ tự này quan trọng? ─────────────────────────
# Bridge CHỈ đọc change đang active (morkit/output/spec/, không
# đọc archive/). Nếu archive trước, intent (WHAT/WHY) của change
# mất hút khỏi docs. Nên: docs update trước, archive sau.
# ──────────────────────────────────────────────────────────
▶ Bạn làm (đúng thứ tự)
$ /morkit:docs update # gấp WHAT/WHY của change vào FEATURE-LIST/ADR/TEST-MATRIX
$ /morkit:archive email-signup-otp # giờ mới đóng change → archive/YYYY-MM/
▼ Kết quả
✓ docs/ giữ đủ WHAT/WHY của change · change đã archive gọn gàng
⚠ change archive khi tasks còn dở → KHÔNG bridge được (đừng archive sớm)
# Vòng đời greenfield: lặp Step 4→7 cho mỗi đợt tính năng. docs/
# lớn dần cùng code, luôn bám sự thật — input tốt cho UC3/UC4/UC5.
Feature mới hoàn toàn — tích hợp TipTap editor để edit note
Step 0 Khám phá repo — hiểu trạng thái 3 nhánh, đề xuất hướng đi
▶ INPUT/morkit:brainstorming
$ /morkit:brainstorming tìm hiểu giúp tôi repo Notion-clone bao gồm các nhánh của nó
▼ OUTPUT Đang ở explore mode — đọc repo, không implement. // branches discovered origin/brainstorming 4e5c629 // 2 nhánh trỏ cùng commit origin/docs 4e5c629 origin/greenfield 67bae32 ← default, working line // active morkit change bootstrap-mortion-v1 status: in-progress tasks 0/64 ⚠ Tension #1 — code đã ship vượt scope của bootstrap (sidebar, command palette, blocks renderer) nhưng tasks.md = 0 ticked. ⚠ Tension #2 — review-checklist gate vẫn = PENDING dù code đã land. → Đề xuất: tách editor-wire-v1 change để wire TipTap thật trước khi persistence.
▼ OUTPUT Đang ở explore mode — đọc repo, không implement. // branches discovered origin/brainstorming 4e5c629 // 2 nhánh trỏ cùng commit origin/docs 4e5c629 origin/greenfield 67bae32 ← default, working line // active morkit change bootstrap-mortion-v1 status: in-progress tasks 0/64 ⚠ Tension #1 — code đã ship vượt scope của bootstrap (sidebar, command palette, blocks renderer) nhưng tasks.md = 0 ticked. ⚠ Tension #2 — review-checklist gate vẫn = PENDING dù code đã land. → Đề xuất: tách editor-wire-v1 change để wire TipTap thật trước khi persistence.
Step 1 Sinh morkit artifacts — proposal · design · tasks · checklist · spec
▶ INPUT/morkit:propose
$ /morkit:propose "editor-wire-v1: TipTap live editing with block UUIDs,
slash menu trigger, drag-handle, in-memory only"
▼ OUTPUT [Context7] Verifying TipTap 3.22 API surface... OK [Context7] Verifying lowlight v3 + extension-code-block-lowlight... OK [Context7] tiptap drag-handle peer deps audit... heavy Đã tạo: morkit/output/spec/editor-wire-v1/ ├── proposal.md (40 dòng) ├── design.md (126 dòng — có ## Tech Stack section) ├── tasks.md (173 dòng — 11 task groups) ├── review-checklist.md (FE-Feature variant, 126 dòng) └── specs/editor/spec.md (123 dòng — 8 Requirements, 17 Scenarios) 🚦 GATE: review-checklist.md có "Overall Decision: PENDING". Hãy đọc + tick các mục, đặt OK trước khi /morkit:executing-plans.
▼ OUTPUT [Context7] Verifying TipTap 3.22 API surface... OK [Context7] Verifying lowlight v3 + extension-code-block-lowlight... OK [Context7] tiptap drag-handle peer deps audit... heavy Đã tạo: morkit/output/spec/editor-wire-v1/ ├── proposal.md (40 dòng) ├── design.md (126 dòng — có ## Tech Stack section) ├── tasks.md (173 dòng — 11 task groups) ├── review-checklist.md (FE-Feature variant, 126 dòng) └── specs/editor/spec.md (123 dòng — 8 Requirements, 17 Scenarios) 🚦 GATE: review-checklist.md có "Overall Decision: PENDING". Hãy đọc + tick các mục, đặt OK trước khi /morkit:executing-plans.
Step 2 🚦 Human review gate — bạn phải review và duyệt, agent SẼ KHÔNG tự động phê duyệt hay sửa file review
▼ HUMAN GATEplan-review-gate
# Plan Review Checklist — `editor-wire-v1`
- [x] Plan có nêu rõ mục tiêu (SMART)
- [x] IN/OUT scope rõ ràng
- [x] Cấu trúc tác vụ TDD (chu kỳ 5 bước / 5-step cycle)
- [x] Component tree liệt kê file path
- [ ] UI states default/loading/empty/error/disabled ← gap (defer)
- [ ] ARIA labels cho drag handle, slash menu ← gap (defer)
...
- Quyết định: OK — 4 minors accepted as v1 trade-off.
```
Overall Decision: OK
```
> signed: duongmh @ 2026-05-10
> PreToolUse hook giờ đã cho phép /morkit:executing-plans, /morkit:subagent-driven-development, …
Step 3 Thực thi 11 task groups (chạy theo TDD) — mỗi group: read → red → green → verify → commit
▶ INPUT/morkit:executing-planstest-driven-development
$ git checkout -b feature/editor-wire-v1
$ /morkit:executing-plans morkit/output/spec/editor-wire-v1/tasks.md
▼ OUTPUT (rút gọn — 11 groups) ▶ Group 1/11 — Vitest + RTL setup RED: tests/sanity.test.ts FAIL (no config) GREEN: vitest.config.ts PASS 2/2 ✓ commit af7dae3 chore(test): set up Vitest + Testing Library ▶ Group 2/11 — UUID utility RED: tests/lib/uuid.test.ts FAIL (regex unmet) GREEN: lib/uuid.ts (Web Crypto) PASS 4/4 ✓ commit c814ed4 feat(lib): add uuid() generator ▶ Group 3/11 — BlockUuid extension RED: block-uuid.test.ts FAIL (id null) // debug: appendTransaction không fire ở initial content load // fix: parseHTML default uuid() khi missing data-id GREEN: components/editor/extensions/block-uuid.ts PASS 8/8 ✓ commit 59dab16 feat(editor): add BlockUuid extension ▶ Group 4/11 → 53b15fb feat(editor): replace Blocks with live Editor ▶ Group 5/11 → ee2d59d feat(editor): wire slash menu via @tiptap/suggestion ▶ Group 6/11 → 814eace feat(editor): drag-handle decoration (DnD UX deferred) ▶ Group 7/11 → 7b91250 feat(editor): Mention (@) + PageLink ([[) nodes ▶ Group 8/11 → 1db79dd feat(editor): code block + lowlight ▶ Group 9/11 → bff55f3 test(editor): keyboard passthrough (⌘K, ⌘⇧L…) ▶ Group 10/11 → 1676421 docs(readme): Status v0 → v1 ▶ Group 11/11 — E2E verify $ npm run lint && npm run typecheck && npm test && npm run build ✔ Không có lỗi hoặc cảnh báo ESLint nào ✔ tsc --noEmit sạch sẽ ✔ Số tệp kiểm thử: 9 tệp đạt (9) · Các ca kiểm thử: 34 ca đạt (34) ✔ Bản build ✓ Biên dịch thành công · dung lượng tệp 229 kB · 332 kB FLJ
▼ OUTPUT (rút gọn — 11 groups) ▶ Group 1/11 — Vitest + RTL setup RED: tests/sanity.test.ts FAIL (no config) GREEN: vitest.config.ts PASS 2/2 ✓ commit af7dae3 chore(test): set up Vitest + Testing Library ▶ Group 2/11 — UUID utility RED: tests/lib/uuid.test.ts FAIL (regex unmet) GREEN: lib/uuid.ts (Web Crypto) PASS 4/4 ✓ commit c814ed4 feat(lib): add uuid() generator ▶ Group 3/11 — BlockUuid extension RED: block-uuid.test.ts FAIL (id null) // debug: appendTransaction không fire ở initial content load // fix: parseHTML default uuid() khi missing data-id GREEN: components/editor/extensions/block-uuid.ts PASS 8/8 ✓ commit 59dab16 feat(editor): add BlockUuid extension ▶ Group 4/11 → 53b15fb feat(editor): replace Blocks with live Editor ▶ Group 5/11 → ee2d59d feat(editor): wire slash menu via @tiptap/suggestion ▶ Group 6/11 → 814eace feat(editor): drag-handle decoration (DnD UX deferred) ▶ Group 7/11 → 7b91250 feat(editor): Mention (@) + PageLink ([[) nodes ▶ Group 8/11 → 1db79dd feat(editor): code block + lowlight ▶ Group 9/11 → bff55f3 test(editor): keyboard passthrough (⌘K, ⌘⇧L…) ▶ Group 10/11 → 1676421 docs(readme): Status v0 → v1 ▶ Group 11/11 — E2E verify $ npm run lint && npm run typecheck && npm test && npm run build ✔ Không có lỗi hoặc cảnh báo ESLint nào ✔ tsc --noEmit sạch sẽ ✔ Số tệp kiểm thử: 9 tệp đạt (9) · Các ca kiểm thử: 34 ca đạt (34) ✔ Bản build ✓ Biên dịch thành công · dung lượng tệp 229 kB · 332 kB FLJ
Step 4 Self-review (deep-review trên local diff) — 5 subagents chạy song song trước khi push code
▶ INPUT/morkit:deep-review
$ /morkit:deep-review --diff
▼ OUTPUT [deep-review] Building call graph (uvx code-review-graph)... [deep-review] Spawning 5 subagents in parallel... • risk · security · pattern · tests · convention ╭─ Risk ────────────────────────────────────────────╮ │ MAJOR .claude-flow/data/pending-insights.jsonl │ │ tooling telemetry leaked (44 lines) │ ╰─────────────────────────────────────────────────────────╯ ╭─ Security ────────────────────────────────────────╮ │ MAJOR blocks-to-html.ts:38 — data-id raw interp. │ │ MAJOR npm audit: 1 HIGH (6 moderate) │ ╰─────────────────────────────────────────────────────────╯ ╭─ Pattern 3 Minor (naming, render() trap, classNames) ╮ ╭─ Tests 1 Major (no XSS test for Block.text) ╮ ╭─ Convention ✓ clean ╮ Tổng: 0 Critical · 4 Major · 7 Minor
▼ OUTPUT [deep-review] Building call graph (uvx code-review-graph)... [deep-review] Spawning 5 subagents in parallel... • risk · security · pattern · tests · convention ╭─ Risk ────────────────────────────────────────────╮ │ MAJOR .claude-flow/data/pending-insights.jsonl │ │ tooling telemetry leaked (44 lines) │ ╰─────────────────────────────────────────────────────────╯ ╭─ Security ────────────────────────────────────────╮ │ MAJOR blocks-to-html.ts:38 — data-id raw interp. │ │ MAJOR npm audit: 1 HIGH (6 moderate) │ ╰─────────────────────────────────────────────────────────╯ ╭─ Pattern 3 Minor (naming, render() trap, classNames) ╮ ╭─ Tests 1 Major (no XSS test for Block.text) ╮ ╭─ Convention ✓ clean ╮ Tổng: 0 Critical · 4 Major · 7 Minor
Step 5 Push + mở PR — bạn sẽ review PR này
▶ INPUT
$ git push -u origin feature/editor-wire-v1
$ gh pr create --base greenfield --title "feat: wire TipTap editor (editor-wire-v1)"
▼ OUTPUT + [new branch] feature/editor-wire-v1 → feature/editor-wire-v1 https://github.com/mor-nhatlq/Notion-clone/pull/1 # 35 files · +4806/−1104 (incl. lock) # 13 commits, conventional, no Co-Authored-By
▼ OUTPUT + [new branch] feature/editor-wire-v1 → feature/editor-wire-v1 https://github.com/mor-nhatlq/Notion-clone/pull/1 # 35 files · +4806/−1104 (incl. lock) # 13 commits, conventional, no Co-Authored-By
Step 6 🚦 Xong task → cập nhật docs: /morkit:docs update → /morkit:archive
— bridge change-spec editor-wire-v1 vào docs/ TRƯỚC khi archive · code = HOW, spec = WHAT/WHY
# ─ Tại sao bước này? ──────────────────────────────────────
# PR merge xong, code đã đổi NHƯNG docs/ chưa biết. Chạy
# /morkit:docs update để: (1) re-scout vùng editor đổi → cập
# nhật docs code-derived, (2) bridge spec editor-wire-v1 (WHAT/
# WHY) vào docs TRƯỚC khi change bị archive — bridge không đọc
# archive/, archive sớm = mất intent (WHAT/WHY) khỏi docs.
# ──────────────────────────────────────────────────────────
▶ INPUT/morkit:docs update
$ /morkit:docs update
▼ OUTPUT [drift] doc lệch theo source_files (vùng editor): M 20-design/40-ui/UI-MAP components/editor/** mới M 00-overview/SOURCE-MAP +lib/uuid · extensions/block-uuid [bridge] change active editor-wire-v1 (tasks ✓ 11/11, chưa archive): spec.md 8 Requirement → 10-requirements/FEATURE-LIST (FR mới / cập nhật) spec.md 17 Scenario → 10-requirements/flows/ + 30-test/TEST-MATRIX (1 scenario = 1 row) design.md Decisions → 20-design/ADR/NNN-tiptap-block-uuid.md design.md Risks → 40-ai-coding/RISK-REGISTER + KNOWN-PITFALLS // code = HOW (canonical). spec khẳng định mà code chưa có → status: drift [write] cập nhật content → re-derive MAP · bump `updated` ✓ giữ phần sửa tay ▶ Đóng change SAU khi đã bridge/morkit:archive $ /morkit:archive editor-wire-v1 # → archive/2026-05/ · WHAT/WHY đã nằm trong docs/ # Thứ tự VÀNG: docs update → archive. docs/ giờ phản ánh đúng # feature vừa ship — input chất lượng cho UC4 (fix) / UC5 (review).
▼ OUTPUT [drift] doc lệch theo source_files (vùng editor): M 20-design/40-ui/UI-MAP components/editor/** mới M 00-overview/SOURCE-MAP +lib/uuid · extensions/block-uuid [bridge] change active editor-wire-v1 (tasks ✓ 11/11, chưa archive): spec.md 8 Requirement → 10-requirements/FEATURE-LIST (FR mới / cập nhật) spec.md 17 Scenario → 10-requirements/flows/ + 30-test/TEST-MATRIX (1 scenario = 1 row) design.md Decisions → 20-design/ADR/NNN-tiptap-block-uuid.md design.md Risks → 40-ai-coding/RISK-REGISTER + KNOWN-PITFALLS // code = HOW (canonical). spec khẳng định mà code chưa có → status: drift [write] cập nhật content → re-derive MAP · bump `updated` ✓ giữ phần sửa tay ▶ Đóng change SAU khi đã bridge/morkit:archive $ /morkit:archive editor-wire-v1 # → archive/2026-05/ · WHAT/WHY đã nằm trong docs/ # Thứ tự VÀNG: docs update → archive. docs/ giờ phản ánh đúng # feature vừa ship — input chất lượng cho UC4 (fix) / UC5 (review).
Bug fix — Unicode normalize trong CommandPalette
Bug nhỏ (file changes ≤2 files): cmdk mặc định không chuẩn hoá Unicode.
Step 0 systematic-debugging — ép quy trình 5 bước, xác định root cause
▶ INPUT/morkit:systematic-debugging
$ /morkit:systematic-debugging "CommandPalette không match
item có dấu khi user gõ form khác"
▼ OUTPUT (5 bước) 📋 1. Tái dựng lỗi tối giản (Reproduce minimal) ✓ ⌘K → gõ "Phân" (NFD via Unikey) → expected "Phân tích" actual: empty list 📊 2. Quan sát thực tế so với mong đợi - cmdk default filter: chuỗi.toLowerCase().includes(query) - Tiếng Việt 2 form: NFC (U+00E2) vs NFD (U+0061 U+0302) - .includes() so sánh bytes → mismatch khi form khác 🌳 3. Cây giả thuyết (Hypothesis tree) H1 — Không khớp chuẩn hóa Unicode (NFC vs NFD) ✓ rất có khả năng (likely) H2 — components/cmd/command-palette.tsx ghi đè bộ lọc H3 — Dữ liệu LỆNH (COMMANDS) có NBSP / dấu kết hợp 🔬 4. Kiểm chứng giả thuyết (Falsify) >> JSON.stringify("Phân") → "Phân" >> JSON.stringify("Phân") → "Phân" ✓ Xác nhận H1 — bỏ qua H2/H3 📍 5. Nguyên nhân gốc rễ (Root cause) 📄 components/cmd/command-palette.tsx (line ~57) Filter prop chưa normalize Unicode. cmdk dùng raw compare. 💡 Cách sửa: thêm bộ lọc tùy chỉnh (custom filter) dùng String.prototype.normalize('NFC')
▼ OUTPUT (5 bước) 📋 1. Tái dựng lỗi tối giản (Reproduce minimal) ✓ ⌘K → gõ "Phân" (NFD via Unikey) → expected "Phân tích" actual: empty list 📊 2. Quan sát thực tế so với mong đợi - cmdk default filter: chuỗi.toLowerCase().includes(query) - Tiếng Việt 2 form: NFC (U+00E2) vs NFD (U+0061 U+0302) - .includes() so sánh bytes → mismatch khi form khác 🌳 3. Cây giả thuyết (Hypothesis tree) H1 — Không khớp chuẩn hóa Unicode (NFC vs NFD) ✓ rất có khả năng (likely) H2 — components/cmd/command-palette.tsx ghi đè bộ lọc H3 — Dữ liệu LỆNH (COMMANDS) có NBSP / dấu kết hợp 🔬 4. Kiểm chứng giả thuyết (Falsify) >> JSON.stringify("Phân") → "Phân" >> JSON.stringify("Phân") → "Phân" ✓ Xác nhận H1 — bỏ qua H2/H3 📍 5. Nguyên nhân gốc rễ (Root cause) 📄 components/cmd/command-palette.tsx (line ~57) Filter prop chưa normalize Unicode. cmdk dùng raw compare. 💡 Cách sửa: thêm bộ lọc tùy chỉnh (custom filter) dùng String.prototype.normalize('NFC')
Step 1 Branch riêng + fix tay — 2 tệp, không qua lệnh /morkit:propose
▶ INPUT
$ git checkout greenfield && git checkout -b fix/cmdk-unicode-normalize
$ # Edit components/cmd/command-palette.tsx
▼ SO SÁNH KHÁC BIỆT (DIFF) + /** + * Normalize a string for fuzzy substring matching that's robust to: + * - Unicode form differences (NFC precomposed â vs NFD a + combining ◌̂) + * - Case differences (English ASCII fold). + */ + function normalizeForSearch(value: string): string { + return value.normalize("NFC").toLowerCase() + } <Command onKeyDown={(e) => { if (e.key === "Tab") e.preventDefault() }} + filter={(value, search) => { + const v = normalizeForSearch(value) + const s = normalizeForSearch(search) + return v.includes(s) ? 1 : 0 + }} >
▼ SO SÁNH KHÁC BIỆT (DIFF) + /** + * Normalize a string for fuzzy substring matching that's robust to: + * - Unicode form differences (NFC precomposed â vs NFD a + combining ◌̂) + * - Case differences (English ASCII fold). + */ + function normalizeForSearch(value: string): string { + return value.normalize("NFC").toLowerCase() + } <Command onKeyDown={(e) => { if (e.key === "Tab") e.preventDefault() }} + filter={(value, search) => { + const v = normalizeForSearch(value) + const s = normalizeForSearch(search) + return v.includes(s) ? 1 : 0 + }} >
Step 2 Verify — dự án mới (greenfield) chưa có bộ kiểm thử cơ sở (vitest baseline)
$ npm run lint && npm run typecheck && npm run build
✔ Không có lỗi hoặc cảnh báo ESLint nào
✔ tsc --noEmit sạch sẽ
✔ Biên dịch thành công · đường dẫn / 159 kB
# Các ca kiểm thử cho normalizeForSearch sẽ được thêm sau khi PR #1 được gộp (merge)
# (vitest baseline đã có trên feature/editor-wire-v1, chưa được chuyển sang greenfield)
Step 3 Push + PR #2 — việc phụ: thêm .claude-flow/ vào .gitignore
$ git add -A && git commit -m "fix(cmd): normalize Unicode (NFC) before
command palette filter"
$ git commit -m "chore(gitignore): add .claude-flow/ + untrack telemetry"
$ git push -u origin fix/cmdk-unicode-normalize
$ gh pr create --base greenfield
https://github.com/mor-nhatlq/Notion-clone/pull/2
Code review — /morkit:deep-review <PR#>
Plugin deep-review kích hoạt 5 subagents
chạy song song để đánh giá: rủi ro · bảo mật · pattern · tests · convention trên diff. Đọc
tệp CLAUDE.md với mức ưu tiên cao nhất. Kết quả đầu ra là bảng phát hiện lỗi chỉ rõ dòng và tệp cụ thể (file:line),
xếp hạng theo độ nghiêm trọng, đưa ra kết luận xem có Approve không, hay yêu cầu thay đổi.
Step 0 Lấy mã nguồn (Checkout) + kích hoạt deep-review — hoặc chạy /morkit:deep-review --diff trên máy cục bộ (local)
▶ ĐẦU VÀO (INPUT)/morkit:deep-review
$ gh pr checkout 1
$ /morkit:deep-review 1
▼ KẾT QUẢ (OUTPUT) [deep-review] Đang lấy thông tin PR 1 + phần khác biệt (diff)... [deep-review] Sự khác biệt PR: 35 tệp thay đổi, +4806 dòng / −1104 dòng [deep-review] Đang dựng sơ đồ gọi hàm (call graph) (uvx code-review-graph)... [deep-review] Đang đọc tệp CLAUDE.md làm ngữ cảnh có độ ưu tiên cao nhất... [deep-review] Đang khởi chạy 5 tác nhân phụ (subagents) song song: ▸ rủi ro (risk) (vùng ảnh hưởng blast radius, lỗi đổ vỡ) ▸ bảo mật (security) (XSS, lộ bí mật, kiểm toán) ▸ khuôn mẫu (pattern) (cách đặt tên, quy chuẩn, cấu trúc) ▸ kiểm thử (tests) (độ bao phủ coverage, các trường hợp biên edge cases) ▸ quy chuẩn (convention) (lỗi cú pháp lint, định dạng format, quy tắc dự án)
▼ KẾT QUẢ (OUTPUT) [deep-review] Đang lấy thông tin PR 1 + phần khác biệt (diff)... [deep-review] Sự khác biệt PR: 35 tệp thay đổi, +4806 dòng / −1104 dòng [deep-review] Đang dựng sơ đồ gọi hàm (call graph) (uvx code-review-graph)... [deep-review] Đang đọc tệp CLAUDE.md làm ngữ cảnh có độ ưu tiên cao nhất... [deep-review] Đang khởi chạy 5 tác nhân phụ (subagents) song song: ▸ rủi ro (risk) (vùng ảnh hưởng blast radius, lỗi đổ vỡ) ▸ bảo mật (security) (XSS, lộ bí mật, kiểm toán) ▸ khuôn mẫu (pattern) (cách đặt tên, quy chuẩn, cấu trúc) ▸ kiểm thử (tests) (độ bao phủ coverage, các trường hợp biên edge cases) ▸ quy chuẩn (convention) (lỗi cú pháp lint, định dạng format, quy tắc dự án)
Step 1 Tạo báo cáo 5 phần (5-section report) — phát hiện lỗi xếp hạng theo độ nghiêm trọng, chỉ rõ file:line
╭─ 🔴 Rủi ro (Risk) ─────────────────────────────────────────╮
│ LỚN (MAJOR) .claude-flow/data/pending-insights.jsonl │
│ Dữ liệu đo lường công cụ (telemetry) bị rò rỉ vào PR (44 dòng). │
│ → Sửa (Fix): thêm .claude-flow/ vào .gitignore + git rm cached │
│ NHẸ (MINOR) components/editor/slash-menu.tsx (giao diện khung không có liên kết orphan) │
╰────────────────────────────────────────────────────────────╯
╭─ 🟠 Bảo mật (Security) ─────────────────────────────────────╮
│ LỚN (MAJOR) blocks-to-html.ts:38 — data-id="${b.id}" │
│ Nguy cơ tiềm ẩn lỗi XSS khi tính năng lưu trữ persistence-v1 được đưa vào.│
│ → Sửa (Fix): escapeHtml(b.id) trước khi nội suy (interpolation) │
│ LỚN (MAJOR) kiểm toán npm audit: phát hiện 1 lỗi CAO (6 trung bình) │
│ Đạt (OK) Link.configure danh sách trắng các giao thức + rel noopener│
│ Đạt (OK) Không sử dụng dangerouslySetInnerHTML trong mã nguồn của ta│
╰────────────────────────────────────────────────────────────╯
╭─ 🟡 Khuôn mẫu (Pattern) ──────────────────────────────────────╮
│ NHẸ (MINOR) cách đặt tên không nhất quán: BlockUuid / DragHandle (không có Node)│
│ so với MentionNode / PageLinkNode (có Node) │
│ NHẸ (MINOR) Suggestion render() trả về các hàm rỗng no-op ("chỉ mang tính tượng trưng")│
│ NHẸ (MINOR) editor.tsx chuỗi lớp Tailwind className dài 150 ký tự │
│ Đạt (OK) Đã tách hàm trợ giúp ensureIds() helper, tập trung một nơi │
╰────────────────────────────────────────────────────────────╯
╭─ 🟢 Kiểm thử (Tests) ────────────────────────────────────────╮
│ LỚN (MAJOR) Không có kiểm thử XSS cho blocksToHtml(Block.text) │
│ Thêm: expect(...).not.toContain('<script>') │
│ Đạt (OK) 34/34 ca kiểm thử đạt · kiểm tra tính duy nhất 1000 của uuid · BlockUuid│
│ Đạt (OK) phím tắt keyboard-passthrough tham số hóa (4 tổ hợp) │
╰────────────────────────────────────────────────────────────╯
╭─ ⚪ Quy chuẩn (Convention) ─────────────────────────────────────╮
│ Đạt (OK) Không dấu chấm phẩy, sử dụng nháy kép theo cấu hình .prettierrc│
│ Đạt (OK) Thông điệp commit theo chuẩn Conventional Commits, không chứa Co-Authored-By│
│ Đạt (OK) Có chú thích JSDoc giải thích mục đích trên mỗi tiện ích mở rộng│
│ Đạt (OK) Chế độ TypeScript nghiêm ngặt, không dùng any, bật noUncheckedIndexedAccess│
╰────────────────────────────────────────────────────────────╯
Tóm tắt (Summary): 0 Nghiêm trọng (Critical) · 4 Lớn (Major) · 7 Nhẹ (Minor)
Khuyến nghị (Recommendation): Yêu cầu thay đổi (Request changes) — sửa rò rỉ .claude-flow +
lọc ký tự đặc biệt (escape) data-id (5+5 phút) trước khi gộp (merge).
Step 2 Khép kín vòng lặp bằng commit sửa lỗi (fix commit) — ý kiến đánh giá (review feedback) → sửa lỗi (fix) → đánh giá lại (re-review)
▶ ĐẦU VÀO (INPUT) (sau khi có ý kiến đánh giá)
$ # Viết kiểm thử lỗi (RED test) cho kiểm soát XSS (XSS contract)
$ npm test tests/editor/blocks-to-html.test.ts 2 lỗi (fail)
$ # Viết mã vượt kiểm thử (GREEN): escapeHtml(b.id) + lọc ký tự đặc biệt trước replace markup
$ npm test 38/38 đạt (pass)
$ git commit -m "fix(editor): escape data-id and Block.text (XSS hardening)"
$ git push
▼ KẾT QUẢ (PR #1 đã cập nhật) 1676421..3e694c9 feature/editor-wire-v1 → feature/editor-wire-v1 # 2/4 lỗi Lớn (Major) đã được giải quyết (resolved) ngay trong cùng PR. # 7 lỗi Nhẹ (Minor) + 2 lỗi Lớn (Major) còn lại hoãn (defer) sang editor-polish-v1. Đường ống khép vòng (Pipeline): Trường hợp sử dụng 2 (tính năng) ─▶ PR #1 │ Đánh giá Trường hợp sử dụng 4 ▼ các phát hiện lỗi được đăng tải │ ──────────────────────── ▼ Sửa lỗi kiểu Trường hợp sử dụng 3 trên cùng PR ▼ PR #1 đã cập nhật
▼ KẾT QUẢ (PR #1 đã cập nhật) 1676421..3e694c9 feature/editor-wire-v1 → feature/editor-wire-v1 # 2/4 lỗi Lớn (Major) đã được giải quyết (resolved) ngay trong cùng PR. # 7 lỗi Nhẹ (Minor) + 2 lỗi Lớn (Major) còn lại hoãn (defer) sang editor-polish-v1. Đường ống khép vòng (Pipeline): Trường hợp sử dụng 2 (tính năng) ─▶ PR #1 │ Đánh giá Trường hợp sử dụng 4 ▼ các phát hiện lỗi được đăng tải │ ──────────────────────── ▼ Sửa lỗi kiểu Trường hợp sử dụng 3 trên cùng PR ▼ PR #1 đã cập nhật
Figma → code — 4 bước MCP chuẩn
Có Figma URL (hoặc đang chọn node trên Figma desktop), muốn dựng thành code
khớp 1:1 với design. Figma chỉ để LẤY design: skill
figma-implement-design + Figma MCP chạy 4 lệnh theo thứ tự cố
định, thu hẹp dần (ảnh → cấu trúc node → ngữ cảnh chi tiết → token biến) để
trích xuất design-as-code + token. Phần BUILD bàn giao sang
morkit — plan · TDD · verify theo convention dự án.
PHASE 0 Lấy node-id — parse từ URL hoặc lấy selection trên Figma desktop
▶ INPUTfigma-implement-design
$ # User dán Figma URL
https://figma.com/design/kL9xQn2VwM8/DesignSystem?node-id=42-15
▼ PARSE fileKey = kL9xQn2VwM8 # segment sau /design/ nodeId = 42-15 # query param node-id # Hoặc dùng figma-desktop MCP: chọn node trong app → khỏi cần URL
▼ PARSE fileKey = kL9xQn2VwM8 # segment sau /design/ nodeId = 42-15 # query param node-id # Hoặc dùng figma-desktop MCP: chọn node trong app → khỏi cần URL
PHASE 1 get_screenshot — ảnh chuẩn thị giác, giữ xuyên suốt để validate cuối
▶ CALLfigma-implement-design
>> get_screenshot(fileKey="kL9xQn2VwM8", nodeId="42-15")
▼ OUTPUT ✓ PNG render của frame → mỏ neo thị giác (source of truth) # Mọi bước sau đối chiếu lại ảnh này, không để code trôi khỏi design
▼ OUTPUT ✓ PNG render của frame → mỏ neo thị giác (source of truth) # Mọi bước sau đối chiếu lại ảnh này, không để code trôi khỏi design
PHASE 2 get_metadata — bản đồ node cấp cao, chọn child cần lấy chi tiết
▶ CALLfigma-implement-design
>> get_metadata(fileKey="kL9xQn2VwM8", nodeId="42-15")
▼ OUTPUT (cây node) 📦 42-15 Card/Pricing FRAME ├─ 42-16 Header TEXT ├─ 42-20 PriceRow AUTO-LAYOUT └─ 42-31 CTAButton INSTANCE → Button # Payload quá to / bị truncate? → dùng metadata chọn đúng child, # rồi gọi get_design_context riêng cho từng node con (vd 42-31)
▼ OUTPUT (cây node) 📦 42-15 Card/Pricing FRAME ├─ 42-16 Header TEXT ├─ 42-20 PriceRow AUTO-LAYOUT └─ 42-31 CTAButton INSTANCE → Button # Payload quá to / bị truncate? → dùng metadata chọn đúng child, # rồi gọi get_design_context riêng cho từng node con (vd 42-31)
PHASE 3 get_design_context — layout / typography / component (trả React + Tailwind)
▶ CALLfigma-implement-design
>> get_design_context(fileKey="kL9xQn2VwM8", nodeId="42-15")
▼ OUTPUT - Auto Layout: vertical, gap 16, padding 24 - Typography: Inter 14/20, weight 600 - Fills: token surface/card, border border/subtle - Trả mẫu code React + Tailwind — coi như mô tả design, KHÔNG phải code cuối
▼ OUTPUT - Auto Layout: vertical, gap 16, padding 24 - Typography: Inter 14/20, weight 600 - Fills: token surface/card, border border/subtle - Trả mẫu code React + Tailwind — coi như mô tả design, KHÔNG phải code cuối
PHASE 4 get_variable_defs — token màu / spacing / font → map sang design system dự án
▶ CALLfigma-implement-design
>> get_variable_defs(fileKey="kL9xQn2VwM8", nodeId="42-15")
▼ OUTPUT (biến Figma → token dự án) surface/card #FFFFFF → --color-surface-card border/subtle #E5E7EB → --color-border-subtle space/4 16px → --space-4 # Ưu tiên token design system dự án thay vì hardcode giá trị từ Figma
▼ OUTPUT (biến Figma → token dự án) surface/card #FFFFFF → --color-surface-card border/subtle #E5E7EB → --color-border-subtle space/4 16px → --space-4 # Ưu tiên token design system dự án thay vì hardcode giá trị từ Figma
PHASE 5 Bàn giao sang morkit — dựng + validate 1:1 — design-as-code của Figma chỉ là nháp; morkit dựng đúng convention rồi verify
▶ HANDOFF → morkit/morkit:writing-plans/morkit:test-driven-development/morkit:verification-before-completion
Figma design-as-code = bản nháp / spec → morkit dựng đúng convention dự án
▼ CHECKLIST validate (so với ảnh PHASE 1) [✓] Layout: spacing / căn lề / kích thước khớp [✓] Typography: font / size / weight / line-height khớp [✓] Màu: dùng token, không hardcode [✓] Reuse component design system thay vì tạo mới [✓] Asset lấy từ payload Figma (localhost src), không thêm icon package [✓] Trạng thái hover / active / disabled đúng design
▼ CHECKLIST validate (so với ảnh PHASE 1) [✓] Layout: spacing / căn lề / kích thước khớp [✓] Typography: font / size / weight / line-height khớp [✓] Màu: dùng token, không hardcode [✓] Reuse component design system thay vì tạo mới [✓] Asset lấy từ payload Figma (localhost src), không thêm icon package [✓] Trạng thái hover / active / disabled đúng design
Figma export HTML → Claude đọc file → mockup UI
Không qua Figma MCP. Bạn (hoặc designer) tự dùng plugin export ngay trong
Figma — Dev Mode export, html.to.design, "Figma to
HTML"… — để xuất design ra file .html + thư mục
asset. Sau đó đưa file cho Claude đọc và dựng lại UI trong stack đích. Hợp khi
máy chưa nối được Figma MCP, hoặc design do bên thứ ba gửi sang dạng file.
Figma chỉ tạo design-as-HTML; phần dựng lại dùng skill
morkit (plan → build → verify).
PHASE 0 Export trên Figma (thủ công) — thao tác trong Figma, ngoài Claude
▼ THAO TÁC TRONG FIGMA
1. Chọn frame / page cần export
2. Chạy plugin export HTML (vd html.to.design / Dev Mode)
3. Lưu kết quả ra ổ đĩa:
📄 design-export/index.html
📁 design-export/assets/ (ảnh, font, svg)
# Không dùng Figma MCP ở use case này — HTML là sản phẩm bạn tự xuất
PHASE 1 Đưa file cho Claude — Claude đọc thẳng file .html bằng Read
▶ INPUT
$ Đọc design-export/index.html rồi dựng lại màn này bằng React + design system của dự án
▼ CLAUDE >> Read("design-export/index.html") ✓ nạp ~640 dòng HTML + inline style
▼ CLAUDE >> Read("design-export/index.html") ✓ nạp ~640 dòng HTML + inline style
PHASE 2 Phân tích cấu trúc từ HTML — bóc layout / style / spacing từ markup export
▼ BÓC TÁCH/morkit:writing-plans
- Cấu trúc: header · hero · grid 3 card · footer
- Spacing: padding 24, gap 16 (đọc từ inline style)
- Màu: #0F172A nền, #6366F1 accent
- Font: Inter 16/24; tiêu đề 28/36 weight 700
- Asset: ảnh trong assets/ → map sang public/ của dự án
# HTML export thường absolute-position + inline style → KHÔNG bê nguyên,
# chỉ dùng làm spec để dựng lại bằng layout chuẩn của dự án
PHASE 3 Mockup lại trong stack đích — dựng component + token dự án, đối chiếu HTML gốc
▼ DỰNG LẠI/morkit:executing-plans/morkit:verification-before-completion
+ components/pricing/PricingSection.tsx
- Layout bằng flex/grid chuẩn (bỏ absolute-position của export)
- Reuse <Card/>, <Button/> có sẵn thay vì div thuần
- Màu / spacing trỏ token design system, không hardcode
▼ VALIDATE
[✓] Mở cạnh nhau: HTML export vs component dựng lại → khớp bố cục
[✓] Responsive theo breakpoint dự án (export thường fixed-width)
[✓] (nếu còn nối Figma MCP) get_screenshot frame gốc → đối chiếu pixel
[✓] npm run build · typecheck sạch
Bộ docs generate — cấu trúc & tác dụng từng template (cho AI Agent)
/morkit:init dựng một taxonomy cố định dưới docs/:
6 nhóm core (00-overview … 90-operations) + sub-taxonomy trong 20-design/.
Mỗi file là một "mỏ neo" (anchor) nhỏ (~100 LOC), liên kết chéo, front-matter nhẹ —
để AI agent nạp đúng context tối thiểu cho mỗi task thay vì đọc cả repo.
3 tier: core luôn tạo · conditional chỉ tạo khi scout thấy component khớp (không folder rỗng) · optional chỉ khi được yêu cầu. Thứ tự sinh luôn là Scout → Content → MAP → agent-instructions (MAP/anchor viết sau cùng để link trỏ tới file thật).
docs/
├─ 00-overview/ SCOPE · DOCUMENT-MAP · SOURCE-MAP · DEPENDENCY-MAP · GLOSSARY · STACK*
├─ 10-requirements/ FEATURE-LIST · USER-FLOWS · flows/FR-NNN-*
├─ 20-design/ DESIGN-MAP · 00-core/{ARCHITECTURE, INVARIANTS} · 10-features/*-SYS-SPEC
│ 20-data/DATA-MAP* · 30-api/API-MAP* · 40-ui/UI-MAP* · ADR/NNN-** · 90-reference/*-REFERENCE°
├─ 30-test/ TEST-STRATEGY · TEST-RUNBOOK · TEST-MATRIX
├─ 40-ai-coding/ AI-CODING-GUIDE · CODE-SEARCH-GUIDE · CODE-STANDARDS* · COMMON-CHANGE-PLAYBOOKS · KNOWN-PITFALLS · RISK-REGISTER
├─ 90-operations/ LOCAL-RUNBOOK · TROUBLESHOOTING
└─ README (root mỏng + mỗi folder) # * = conditional (scout thấy) · ° = optional
00-overview/ — Cửa ngõ điều hướng & bản đồ code
Core. Agent đọc nhóm này TRƯỚC để định hướng và biết code nằm ở đâu.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
SCOPE.md | core | In Scope · Out of Scope · Boundaries (must own / must NOT own) | Chặn agent sửa vượt ranh giới module |
DOCUMENT-MAP.md | core | Directory Roles · Read Paths (theo task) · Canonical Source Rules | Định tuyến: đọc doc nào, thứ tự nào cho từng loại task |
SOURCE-MAP.md | core | Concern→Source · Key Symbols · Code Search Keywords · Source Boundaries | Mỏ neo concern→file→symbol → grep đúng chỗ ngay |
DEPENDENCY-MAP.md | core | Internal · External · Data · Cross-Module dependencies | Thấy tác động phụ thuộc trước khi sửa |
GLOSSARY.md | core | Terms→nghĩa→source ref · Status/Enum values | Giải nghĩa jargon, trỏ định nghĩa canonical trong code |
STACK.md | conditional | Tech stack · repo layout · entry points · LOC (scout: có manifest package.json/pyproject…) | Một chỗ nắm hình dạng dự án + điểm vào (entry point) |
10-requirements/ — WHAT: hệ thống làm gì
Core. Catalog tính năng + luồng người dùng. Cấp ID FR-/NFR- dùng xuyên suốt design & test.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
FEATURE-LIST.md | core | Legend · Actors · bảng FR (FR-ID→feature→module→status→value→spec) · bảng NFR | Nguồn DUY NHẤT cấp FR-/NFR-, chống trôi định nghĩa feature |
USER-FLOWS.md | core | Flow Index (per-feature) hoặc inline flows (happy / error) | Đối chiếu hành vi code khớp UX dự kiến, không chỉ đúng kỹ thuật |
flows/FR-NNN-*.md | core | Happy Path · Alternate/Error Paths · Touchpoints (screen/API/table) | Đảm bảo mọi screen/API trong flow được sửa cùng nhau |
20-design/ — HOW: kiến trúc, spec, bản đồ data/API/UI
Core + conditional. 00-core & 10-features luôn có; data/api/ui/ADR/reference tạo theo tín hiệu scout.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
DESIGN-MAP.md | core | Design Layers (doc→purpose) · System Overview flow · Key Decisions (+ADR links) | Định hướng tầng design + dòng dữ liệu trong 1 lần đọc |
00-core/ARCHITECTURE.md | core | arc42-lite: Goals · Constraints · Context · Strategy · Building Blocks (CMP/LAY id) · Runtime · Crosscutting | Mô hình hệ thống đầy đủ: tầng nào tương tác, component nào sở hữu concern nào |
00-core/INVARIANTS.md | core | INV-### theo nhóm: Access Control · Data Integrity · Async · Integrations · Settings · Legacy | Guard-rail: kiểm trước khi code; mỗi INV gắn TEST-MATRIX |
10-features/*-SYS-SPEC.md | core | Purpose · Source Anchors (layer→file) · Behavior/Flow · Business Rules (BR-###) · Change Impact | Context đầy đủ 1 feature: đọc flow → biết file sửa + cần test gì |
20-data/DATA-MAP.md | conditional | MAP-mode (table roles + key cols + trỏ schema) hoặc FULL-mode (ERD + DDL) (scout: schema/migrations/ORM) | Trỏ schema nguồn, không nhân bản DDL → khỏi lỗi lệch |
30-api/API-MAP.md | conditional | Endpoints (method·path·handler·auth) · params · error conventions (scout: routes/controllers) | Tra endpoint + handler + auth mà không cần mở code |
40-ui/UI-MAP.md | conditional | App structure · routes→components · key components · UI gotchas (scout: frontend/components) | Tra nhanh route→component + ràng buộc UI baked-in |
ADR/NNN-*.md | conditional | MADR: Context · Decision · Consequences · Alternatives (status/date) (scout: có quyết định kiến trúc) | Hiểu WHY trước khi đổi HOW → tránh undo quyết định cũ |
90-reference/*-REFERENCE.md | optional | Pointer doc: schema/route/frontend sources + grep anchors (KHÔNG nhân bản nội dung) | Đích grep canonical; các MAP trỏ vào đây |
30-test/ — Test: chiến lược, cách chạy, truy vết
Core. Cho agent biết test gì, chạy thế nào, và requirement nào đã được phủ.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
TEST-STRATEGY.md | core | Existing Coverage · Priority Areas (theo risk) · Test Levels · Manual Focus | Biết test gì & vì sao — dồn sức vào vùng rủi ro cao |
TEST-RUNBOOK.md | core | Lệnh chạy theo stack · Manual Verification · Minimal checks theo loại đổi · Gaps | Copy-paste lệnh test + mức kiểm tối thiểu trước khi submit |
TEST-MATRIX.md | core | 1 dòng / case: Ref(FR/NFR/INV)→Feature→Case→Expected→Status | Truy vết requirement↔test, thấy ngay gì còn TODO |
40-ai-coding/ — Hướng dẫn tối ưu riêng cho AI agent
Core (trừ CODE-STANDARDS). Nhóm "dành cho agent": đọc gì trước, grep thế nào, tránh lỗi gì.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
AI-CODING-GUIDE.md | core | Before Editing (read order) · Safe Change Workflow 6 bước · Notes for agents | Doc agent mở ĐẦU TIÊN: đọc gì, theo thứ tự nào trước khi sửa |
CODE-SEARCH-GUIDE.md | core | Công thức rg theo task (entry · data-flow · config · auth · schema · routes · tests) | Lệnh grep sẵn, khỏi đoán pattern |
CODE-STANDARDS.md | conditional | Tooling · Formatting (FMT-###) · Naming · Lint · Commit · Branch/PR · hooks (scout: lint/format/commit config) | Format/lint đúng mà không cần chạy thử — facts, không phải prose |
COMMON-CHANGE-PLAYBOOKS.md | core | Các bước cho từng loại đổi (add entity/field · change rule · add module · remove/deprecate) — kết bằng "update docs" | Theo playbook có sẵn, luôn nhắc bước cập nhật docs |
KNOWN-PITFALLS.md | core | Bảng: Pitfall → Why It Happens → How To Avoid | Thấy lỗi thường gặp + cách tránh TRƯỚC khi mắc |
RISK-REGISTER.md | core | Bảng: Risk → Impact → Mitigation (cấp hệ thống/business) | Thấy hậu quả production + cách giảm thiểu |
90-operations/ — Vận hành local & xử lý sự cố
Core. Giúp agent chạy app và chẩn đoán lỗi runtime.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
LOCAL-RUNBOOK.md | core | Start (lệnh / service) · URLs · DB checks · Verify Key Operations | Chạy app local mà không phải đào docs |
TROUBLESHOOTING.md | core | Theo từng triệu chứng → checks xếp từ rẻ/nhanh → tốn | Mô tả triệu chứng → nhảy đúng mục, check theo chi phí |
README — Cửa vào (root + mỗi folder)
Core. Trang landing mỏng cho docs/ và mini-map cho từng folder.
| Template | Tier | Cấu trúc chính | Tác dụng cho AI Agent |
|---|---|---|---|
README (root) | core | 1 câu mô tả · Canonical Docs (chỉ link anchor chính, không path source) | Cửa vào → nhảy ngay sang DOCUMENT-MAP đọc theo thứ tự |
README (mỗi folder) | core | Vai trò folder 1 câu · Docs (file→mô tả) · Related (link folder anh em) | Định hướng nhanh trong folder, khỏi mò file |
Vì sao tách nhỏ & gắn front-matter? Mỗi anchor ~100 LOC để agent đọc nhanh, không nuốt cả file lớn.
source_files trong front-matter là hạt giống cho /morkit:docs update dò drift;
status (draft/stable/planned/drift) đánh dấu intent vs đã-bám-code. Quy ước đầy đủ: xem
references/taxonomy.md + anchor-conventions.md trong skill writing-docs.