# /generate-tech-docs — Sinh Tài liệu Thiết kế Kỹ thuật (một doc gộp per-PRD) > **Mô hình phạm vi:** MỘT tài liệu thiết kế kỹ thuật cho mỗi **PRD**, không phải > per-UC — một blueprint **full-stack, gộp** (backend API/data/DB **và** client > component/state/integration trong một file, nối bằng sequence diagram xuyên > tầng) để bất kỳ dev nào đọc là implement được cả feature. > > **Tech lead trỏ lệnh vào (các) file BDD cụ thể cần thiết kế lúc này** — một file, > hoặc một batch nhỏ (vd `system/` + `web/` + `app/` của cùng một UC). Lệnh chỉ nạp > **đúng các file đó** (giữ context nhỏ) rồi ghi/mở rộng tài liệu tech-design duy > nhất của PRD. Chạy lại cho (các) file BDD kế tiếp thì doc **lớn dần** — mỗi lần > chạy là **append**, không bao giờ regenerate toàn bộ. Lệnh KHÔNG tự gom mọi BDD > của PRD (sẽ nổ context). ## Gate # Gate — Quy trình vào chuẩn cho mọi lệnh Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó. ## Bước 0 — Kiểm tra chế độ Sub-Agent Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không: 1. Thử parse `$ARGUMENTS` dưới dạng JSON. 2. Nếu parse thành công **và** chứa `"_agent_mode": true`: - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.** - Đặt target file = `payload.target_file` - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md) - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này) - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD) - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này) - Đi thẳng tới phần logic riêng của lệnh. 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường). ## Bước 0-B — Kiểm tra Model *Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).* Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh. Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc. Hiển thị và chờ phản hồi: ``` ⚙️ MODEL CHECK ────────────────────────────────────────────────────────────────── Recommended : claude-opus-4 (hoặc model Opus mới nhất) Why needed : Phân tích spec, review kiến trúc, sinh code đòi hỏi suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case. Cách đổi trong Claude Code: • Settings → Model → chọn "claude-opus" • hoặc: /model → chọn claude-opus Đang chạy claude-opus? Y — đúng, đang dùng claude-opus → tiếp tục S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại) ────────────────────────────────────────────────────────────────── ``` - "Y" → tiếp tục sang Bước 1. - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối). - "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này." ## Bước 1 — Xác định Target File 1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target. 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`): - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó. - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)* - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`. - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`. Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi. 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp: - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD). - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)" - Chờ người dùng chọn rồi mới tiếp tục. ## Bước 2 — Chạy Context Loader Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`. Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh. ## Bước 3 — CHECKPOINT Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận: ``` CHECKPOINT ----------- Target : {resolved file path} Project : {project.name từ project-context.yaml} Tech stack : {language} / {framework} Module : {module nếu có, else "not configured"} Domains : {danh sách domain, ngăn cách bởi dấu phẩy} Tiếp tục? (Y/N) ``` Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục. - "Y" → tiếp tục sang các bước riêng của lệnh bên dưới. - "N" → dừng lại và hỏi người dùng muốn thay đổi gì. *Với lệnh này, `$ARGUMENTS` là **input BDD tech lead chọn tường minh** — một hay nhiều path `.feature` và/hoặc UC-id (cách nhau bằng khoảng trắng), KHÔNG phải cả PRD để glob. Phân giải mỗi tham số thành một `.feature` (Gate Bước 1: `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature`), gom vào `input_features` (batch), và suy `{domain}` + `{prd-slug}` + `{TICKET-ID}` từ (các) path khớp — tất cả PHẢI cùng một PRD. Output là doc gộp **duy nhất** của PRD; lần chạy này chỉ thiết kế (các) UC có trong `input_features`.* ## Context # Context Loader — Nạp toàn bộ context dự án Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nhớ trong suốt phiên làm việc của lệnh. **Hướng dẫn ưu tiên (chống lost-in-middle):** - Bước 1–2 là PROJECT-CONFIG — nạp trước, phân giải mọi path và metadata. - Bước 3 là CRITICAL — kiến trúc + coding standards, là các sự thật ưu tiên cao nhất khi sinh nội dung. - Bước 4 là SAFETY — quy tắc bảo vệ dữ liệu, thực thi ngầm suốt cả phiên. - Bước 5–6 là DOMAIN KNOWLEDGE — thuật ngữ và định nghĩa entity. - Bước 7 là WORKING MEMORY RECAP — chốt các sự thật quan trọng lên đầu bộ nhớ làm việc. --- ## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml Đọc `.agent/project-context.yaml`. Trích xuất và lưu: **Tech Stack:** - `tech_stack.language` → ngôn ngữ đang dùng (vd: Java 17, TypeScript, C#, Go) - `tech_stack.framework` → framework đang dùng (vd: Spring Boot 3.2, Angular 17, .NET 8) - `tech_stack.build_tool` → build tool (vd: Maven, npm, dotnet, go) - `tech_stack.test_framework` → test framework (vd: JUnit 5 + Mockito, Jest, xUnit) - `tech_stack.database` → database (vd: PostgreSQL, MySQL, MongoDB) - `tech_stack.module` → module profile đang dùng (vd: java-spring, angular, dotnet, golang, context-engineering) **Conventions:** - `conventions.build_command` → cách compile/build - `conventions.test_command` → cách chạy test - `conventions.service_run` → cách khởi động service - `conventions.ticket_prefix` → tiền tố ticket ID (vd: PROJ, FEAT, UC) **Domains:** - `domains` → danh sách các business domain đang hoạt động **Paths (nếu có):** - `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder) - `paths.refinement_dir` → thư mục output cho findings/review - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`) - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè) - `paths.product_definitions_dir` → gốc product definition - `paths.domain_knowledge_dir` → gốc domain knowledge - `paths.business_dictionary` → path tới business-dictionary.md - `paths.core_entities` → path tới core-entities.md - `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`) - `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ) Nếu không có section `paths`, dùng các giá trị mặc định: - `specs_dir` = `specs` - `refinement_dir` = `.agent/review` - `qc_dir` = `docs` - `qc_skills_dir` = `.agent/skills/qc` - `product_definitions_dir` = `specs/product-definition` - `domain_knowledge_dir` = `specs/domain-knowledge` - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md` - `core_entities` = `specs/domain-knowledge/core-entities.md` - `tech_docs_dir` = `specs` - `trace_dir` = `.trace` Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng. **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ: - `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice` - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)* - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)* - `specs/payment/create-invoice/tech-docs/PAY01-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)* - `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice` Mọi artifact cùng cấp của một feature (PRD, BDD của từng platform, tech-docs BE + FE, design-spec, và trace TSV) đều phân giải về **cùng một `prd_slug`** — nên một BDD **system** hay tech-doc **system/BE** được tổng hợp sẽ nằm chung package `{specs_dir}/{domain}/{prd-slug}/` với các artifact web/app mà nó được suy ra từ đó. Nếu `tech_stack.module` được đặt, đồng thời nạp `.agent/modules/{module}/stack-profile.yaml` nếu file tồn tại. --- ## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella) *Bỏ qua hoàn toàn bước này nếu `setup.mode` không phải `"umbrella"` và không có section `services` trong project-context.yaml.* Nếu có section `services`: **1. Phát hiện active domain** (theo thứ tự ưu tiên): - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file) - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1. *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)* - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir` **2. Route tới service** — nếu active domain khớp với một key trong `services`: - Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây. - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây. - Lưu `active_service` = `services.{domain}.path` - Lưu `active_service_module` = `services.{domain}.module` - Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`) **3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp: - Giữ path mặc định từ Bước 1 - Đặt `active_service = unresolved` **4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`: - Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)* - Override `paths.tech_docs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt** (bước 2 không còn pin tech-docs theo service trong trường hợp này). Tech-docs nằm tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. Tech-design CHÍNH LÀ API contract liên team: BE viết ở đây, FE/App đọc nó từ cùng spec submodule tại `/generate-code --phase=integration`. *(tech-docs theo service chỉ xảy ra khi không có `spec_source` — repo BE thuần đa-service không có spec module dùng chung.)* - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge` - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md` - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md` - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports` - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals` - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests` - Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)* - Override `paths.refinement_dir` → `{spec_source}/.agent/review` — **luôn khi `spec_source` được đặt.** Findings review (`/refine-prd`, `/review-context`, `/review-tech-docs`) là artifact liên-team *về* tài liệu trong spec repo (PRD/BDD/tech-design) — thuộc cùng khu vực ghi với `.trace/` và `feedback/`. Các lệnh review chạy từ working dir của service (BE repo) nhưng **ghi findings vào `{spec_source}/.agent/review/`**, KHÔNG phải `.agent/review` của service repo. Bên trong flat, phân biệt bằng tên file đã prefix `{prd-slug}`/`{UC-ID}`/`{TICKET-ID}`. *(`.agent/review` theo service chỉ khi không có `spec_source`.)* > **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **trạng thái coverage `.trace/`**, **và findings review `.agent/review/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/`, `.agent/review/` và `feedback/` là khu vực **ghi** của dev/QC/reviewer trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo. --- ## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella) *Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.* Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`): **1. Định vị config của service** — thử theo thứ tự ưu tiên: - `{active_service}/.agent/project-context.yaml` - `{active_service}/project-context.yaml` **2. Nếu tìm thấy, override bằng giá trị riêng của service:** | Biến | Nguồn | |----------|--------| | `conventions.test_command` | `conventions.test_command` của service | | `conventions.build_command` | `conventions.build_command` của service | | `paths.trace_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.trace`); bỏ qua mọi `trace_dir` cấp service.** Chỉ khi không có `spec_source`: `{active_service}/{service paths.trace_dir}` (mặc định `{active_service}/.trace`). | | `paths.specs_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/specs`); bỏ qua mọi `specs_dir` cấp service** (mọi spec artifact đều liên team, không bao giờ theo service ở chế độ này). Chỉ khi không có `spec_source`: `{active_service}/{service paths.specs_dir}` nếu được set, else dùng override ở Bước 1.5. | | `paths.refinement_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.agent/review`); bỏ qua mọi `refinement_dir` cấp service** (findings review là artifact liên team). Chỉ khi không có `spec_source`: `{active_service}/.agent/review`. | **3. Lưu** `service_root = {active_service}` làm mốc thư mục làm việc cho mọi lệnh phía sau: - Các lệnh shell (`/dev-run-test`, `/dev-gen-test`) chạy **bên trong** `service_root` - **File source/test** được ghi tương đối với `service_root`; **trace TSV** được ghi vào `{paths.trace_dir}` (là spec repo khi `spec_source` được đặt — một thao tác ghi liên-repo, commit/push vào spec submodule giống như `feedback/`). **4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override). --- ## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện) Nếu `tech_stack.module` được đặt, đọc `.agent/modules/{module}/stack-profile.yaml`. Merge các convention riêng của framework (layer pattern, test pattern, quy tắc đặt tên) vào context đã nạp. Nếu file không tồn tại → bỏ qua âm thầm. --- ## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay) *Đây là context ưu tiên cao nhất — nó định nghĩa CÁCH viết code và tài liệu cho dự án này.* CLAUDE.md được nạp theo **hai tầng** để các quy tắc toàn-umbrella và kiến trúc/coding standards riêng của service kết hợp đúng cách. Agent luôn đứng ở gốc umbrella, nhưng code triển khai nằm trong một service submodule với stack, kiến trúc, và convention RIÊNG của nó — nên CLAUDE.md của service phải thắng khi sinh code. **Tầng 1 — [BASE] Root CLAUDE.md (toàn umbrella).** Đọc `CLAUDE.md` ở gốc repo. Coi nội dung của nó là **nền tảng dùng chung** cho cả umbrella — git convention, tư thế bảo vệ dữ liệu, quy tắc xuyên suốt, và (ở chế độ single-service) là kiến trúc + coding standards duy nhất của dự án. **Tầng 2 — [OVERLAY] Service CLAUDE.md (chỉ chế độ umbrella).** *Chỉ chạy nếu `service_root` đã được set ở Bước 1.6 (tức đã route tới một service thật).* Đọc `{service_root}/CLAUDE.md`. File này định nghĩa kiến trúc + coding standards của **stack thực sự đang được triển khai** (vd: `user-service` = java-spring, `web` = nextjs). Overlay nó lên trên Tầng 1: **khi có xung đột, giá trị của service THẮNG** cho kiến trúc, coding standards, và error handling. Các giá trị Tầng 1 mà service không định nghĩa lại (vd: git convention, banned pattern dùng chung toàn tổ chức) vẫn có hiệu lực. Từ kết quả **đã merge**, trích xuất và lưu: - **§1 Project Overview** → tên dự án, ngôn ngữ, framework, lệnh build/test, domains - **§2 Architecture** → thứ tự layer (vd: Controller → Facade → Service → Repository), quy tắc kiến trúc — *service overlay thắng* - **§2 Package Layout** → **base package** (vd `vn.edupia.{service}`) + **chiến lược đặt package** (by-layer / by-feature) + nơi code một domain sống. Đây là **quy ước đặt code trên đĩa**, PHẢI enforce khi sinh code. Nếu §2 chỉ nêu base package + thứ tự layer mà **không** nói tới sub-package theo feature → hiểu là **by-layer**: các layer đặt **TRỰC TIẾP** dưới base package (vd `vn.edupia.{service}.service`, `.repository`); feature/UC/prd-slug **KHÔNG** thành sub-package, chỉ phân biệt ở **tên class**. Lưu `code_base_package` + `package_strategy` — *service overlay thắng*. - **§3 Coding Standards** → quy tắc đặt tên (class, method), kiểu response wrapper, pattern bị cấm — *service overlay thắng* - **§5 Error Handling** → kiểu exception, mapping HTTP status code, tên class not-found exception — *service overlay thắng* - **§7 Git Conventions** → pattern đặt tên branch, format commit message — *lấy theo root trừ khi service định nghĩa lại* **Quy tắc phân giải:** - Nếu cả hai tầng tồn tại → merge như trên; ghi `claude_md_source = root + {service_root}`. - Nếu chỉ có service overlay (không có root CLAUDE.md) → dùng file service một mình; `claude_md_source = {service_root}`. - Nếu `service_root` được set nhưng `{service_root}/CLAUDE.md` **thiếu** → fallback về root CLAUDE.md và gắn cờ ⚠️ trong recap Bước 7 (service không có định nghĩa kiến trúc/coding-standards — việc sinh code sẽ dùng mặc định umbrella, có thể sai stack). - Nếu cả hai đều không tồn tại → ghi nhận CLAUDE.md thiếu và tiếp tục chỉ với dữ liệu từ project-context.yaml. --- ## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework). Lưu các pattern file nhạy cảm — bạn **tuyệt đối không** đọc, ghi, hiển thị, hay tham chiếu nội dung từ các file khớp những pattern đó trong suốt cả phiên. Nếu cả hai file đều không tồn tại → áp dụng mặc định built-in: không bao giờ truy cập `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`. --- ## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện) Kiểm tra file business dictionary có tồn tại không (dùng `paths.business_dictionary` đã phân giải ở Bước 1). Nếu tồn tại, đọc và trích xuất: - **Canonical Terms** → danh sách đầy đủ các thuật ngữ chuẩn và định nghĩa - **Banned Terms** → danh sách đầy đủ các thuật ngữ bị cấm và bản thay thế chuẩn - **Status / Enum Registry** → các giá trị enum được phép theo từng entity Lưu danh sách banned term để **thực thi chủ động** suốt phiên làm việc của lệnh: - Khi sinh bất kỳ văn bản nào (PRD, BDD, comment code, tech docs), kiểm tra không có banned term nào xuất hiện - Tự động thay banned term bằng bản chuẩn tương đương Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn. --- ## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện) Kiểm tra file core entities có tồn tại tại `paths.core_entities` không (đã phân giải ở Bước 1). Path mặc định: `specs/domain-knowledge/core-entities.md`. Nếu tồn tại, đọc và lưu: - **Entity catalog** → với mỗi entity: tên, mục đích, service sở hữu, các field chính (tên + kiểu), business invariant, và quan hệ - **Field name registry** → tên field chuẩn dùng trong code và tài liệu được sinh ra - **Relationship map** → cách các entity liên hệ với nhau (1:N, N:N, embedded, v.v.) **Cách dùng catalog này:** - Khi sinh code: dùng tên field, kiểu, và quan hệ định nghĩa ở đây — KHÔNG suy đoán từ code có sẵn - Khi sinh PRD/BDD: tham chiếu tên entity từ catalog này để nhất quán - Khi sinh tech-docs: dùng catalog này làm nguồn chân lý cho định nghĩa entity Nếu file không tồn tại → bỏ qua âm thầm. --- ## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type Dùng `tech_stack.module` đã nạp ở Bước 1, suy ra và lưu hai biến để mọi lệnh phía sau dùng: ``` active_module = tech_stack.module (vd: "java-spring", "react", "flutter") ``` | `platform_type` | Modules | |---|---| | `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` | | `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` | | `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` | Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7. Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test). --- ## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện) *Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn` hoặc được chấp nhận trong `/review-code`, `/fix-bug`, `/debug`.* Phân giải path file lessons: - Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6) - Else mặc định `specs/domain-knowledge/lessons-learned.md` - Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md` Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên: - Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3). - Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file). - Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng. Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận). --- ## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle) Sau khi nạp toàn bộ context, tổng hợp và xuất một khối tóm tắt gọn. Recap này đảm bảo các sự thật quan trọng nhất được nêu ở CUỐI quá trình nạp context (hiệu ứng recency — tươi mới nhất trong bộ nhớ làm việc khi bắt đầu task). Xuất đúng khối này: ``` [CTX LOADED] Stack : {language} / {framework} / {database} Platform : {active_module} ({platform_type}) Layers : {thứ tự layer từ CLAUDE.md §2 đã merge, vd: Controller → Facade → Service → Repository} Package : {code_base_package}.{layer} · {by-layer | by-feature} ← feature/UC → tên class, KHÔNG thành package (nếu by-layer) CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️ service overlay THIẾU — dùng root | missing} Ticket : {ticket_prefix}- Dict : {loaded — N canonical terms, M banned terms | missing} Entities : {loaded — EntityA, EntityB, EntityC | missing} Lessons : {loaded — N guardrails | chưa có} Service : {active_service} ({active_service_module}) | single-service Svc Root : {service_root} — đã nạp conventions + trace_dir từ config service | — Status : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL} ``` Nếu bất kỳ file CRITICAL nào thiếu (CLAUDE.md), gắn cờ rõ ràng để người dùng quyết định có tiếp tục hay không. --- ## Hoàn tất nạp Context Sau khi hoàn thành tất cả các bước, bạn đã nạp: - Định danh dự án, tech stack, convention module - Quy tắc kiến trúc và thứ tự layer ← **[CRITICAL — giữ trong bộ nhớ làm việc]** - Coding standards và quy tắc đặt tên ← **[CRITICAL — giữ trong bộ nhớ làm việc]** - Quy tắc bảo vệ dữ liệu (pattern file nhạy cảm không bao giờ truy cập) - Quy tắc thuật ngữ kèm danh sách banned term ← **[DOMAIN — áp dụng cho mọi từ được sinh ra]** - Entity catalog (tên field, kiểu, invariant) ← **[DOMAIN — dùng khi sinh code]** - Toàn bộ path đã cấu hình Tiếp tục sang bước kế tiếp của lệnh đang gọi. --- ## Bước 0 — Phân giải batch đầu vào (file mà tech lead trỏ vào) 1. Parse `$ARGUMENTS` thành danh sách feature tech lead chọn. Mỗi token là một path `.feature` hoặc một UC-id; phân giải mỗi cái thành file thật (Gate Bước 1). Danh sách này là `input_features` — **batch được thiết kế trong lần chạy này**. **Đừng** mở rộng nó bằng cách glob BDD anh em; chỉ nạp đúng các file này. 2. **Phân giải định danh từ header, KHÔNG từ tên file.** Với mỗi feature đọc `# @trace.prd` → `{TICKET-ID}` và `# @trace.id` → `{UC-ID}` (cả hai không chứa slug và là chuẩn; TICKET-ID như `FEAT-01-2` có dấu gạch, và slug/title của một UC có thể khác nhau theo platform — vd `…-UC3-sua-cau-bo-qua` (system) vs `…-UC3-sua-cau-quay-lai-bo-qua` (web), nên **đừng bao giờ** parse tên file bằng chuỗi). `{domain}` + `{prd-slug}` lấy từ path (Gate Bước 1). Gom batch thành các UC theo `@trace.id`, để cùng một UC trên system/web/app là **một** UC. Lấy **title** chuẩn của mỗi UC từ PRD (không phải title feature riêng theo platform). **Guard cùng-PRD:** nếu `@trace.prd` khác nhau trong batch → DỪNG: *"Các file thuộc PRD khác nhau ({list}). Chạy /generate-tech-docs mỗi PRD một lần."* 3. **Cảnh báo mềm cỡ batch (không chặn):** nếu `input_features` có **hơn 5** file: ``` ⚠️ {N} file BDD trong một lần chạy. Batch lớn nạp nhiều context hơn và có thể làm giảm chất lượng thiết kế. Cân nhắc chia nhỏ (vd theo UC, hoặc theo platform). Tiếp tục với cả {N}? (Y/N) ``` Y → tiếp tục với tất cả · N → để tech lead chạy lại với ít file hơn. 4. Với mỗi feature trong batch, đọc header + body: `@trace.service`, `@trace.module`, `@trace.platform`, `@trace.bdd_version`, `@trace.status`, `@trace.api_source`, UC id, các scenario (`SC{n}`), và business rule được tham chiếu (`BR{m}`). 5. Xác định **các platform có trong batch** — cái này quyết định lần chạy sinh ra gì: - feature `system/` → sinh/mở rộng các section **backend** (§2–§4.4, §6–§8) cho UC của nó. - feature `web/` và/hoặc `app/` → sinh/mở rộng block **client §4.5** cho platform đó, và thêm flow của platform đó vào lane **§5** (5.B/5.C). - batch không có feature client → không có việc §4.5 lần này (lần chạy sau trỏ vào BDD `web/`·`app/` sẽ append). - **batch không có feature `system/` (PRD chỉ client):** **đừng** bịa BE contract. §4.1 chỉ liệt kê các endpoint mà client **tiêu thụ** (external / bên thứ ba / của team khác / existing), reverse-document từ mệnh đề Then của client BDD + PRD và đánh dấu "consumed (external)"; nếu feature không gọi mạng → §4 = "N/A — client-only, không backend". §4.5.4 map tới bất cứ gì §4.1 liệt kê (hoặc không có). - Ghi `@trace.bdd_version` dưới dạng **map theo platform** (vd `system=1.5, web=1.9`) từ chính `@trace.bdd_version` của mỗi feature — đừng làm phẳng về một số. 6. Đường dẫn output — doc **duy nhất** của PRD: ``` {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md ``` *(Không có `{UC-ID}` và không có hậu tố `-{platform}` — một doc gộp per-PRD lớn dần qua các lần chạy.)* Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC, và `output_path`. --- ## Bước 1 — Chế độ Fresh vs Append Kiểm tra `output_path` đã tồn tại chưa. - **Chưa tồn tại → chế độ FRESH.** Tạo doc từ template, chỉ điền (các) UC trong `input_features`. (Section của các UC không thuộc batch này giữ placeholder `{…}` / được thêm ở lần chạy sau.) - **Đã tồn tại → chế độ APPEND.** Doc là tăng dần — không bao giờ regenerate từ đầu (sẽ đè mất chỉnh tay và sign-off của reviewer). Đọc bảng **§10 UC Coverage** và **Changelog** hiện có → `covered_ucs`. Với mỗi UC trong `input_features`, phân loại: - **UC mới** (không có trong `covered_ucs`) → **thêm** các section của nó: sequence diagram §5 mới **đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối cùng hiện có *trong lane đó*); với §4.5 — nếu **platform** này mới với doc → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm platform đó (đừng lặp nhóm); row mới ở §3/§4.3/§8/§9. Rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog. - **UC đã phủ được trỏ lại** (có trong `covered_ucs`) → đây là refresh/mở rộng có chủ đích (vd tech lead giờ trỏ vào BDD `web/` của một UC mà backend đã thiết kế, hoặc BDD bump version). Xác nhận trước khi đụng nội dung có sẵn: ``` ↻ {UC-ID} đã có trong {TICKET-ID}-tech-design.md. Lần chạy này sẽ {thêm block client {platform} (§4.5) | refresh cho BDD v{new}}. Cập nhật các section của UC này? (Y = merge/mở rộng · N = bỏ qua UC này) ``` Y → merge (thêm platform/§ còn thiếu hoặc refresh phần đã đổi, giữ nguyên prose không liên quan) · N → bỏ qua UC đó. Lưu `mode` (`fresh` | `append`) và, theo từng UC của batch, hành động của nó (`add-new` | `extend-platform` | `refresh` | `skip`). Nếu mọi UC đều `skip` → báo "không có gì để làm" và dừng. --- ## Bước 2 — Cổng Chất lượng (mọi feature nguồn) Với **mỗi** feature BDD trong scope: 1. Tìm `{paths.refinement_dir}/{uc-id}-{platform}-review-bdd-findings.yaml` — `{platform}` = `@trace.platform` của chính feature này (đọc ở Bước 0). Findings là **per (UC × platform)**: mỗi `.feature` của từng platform được review vào file riêng, nên kiểm đúng file khớp feature **này** — không phải của platform anh em (feature `system` phải được gác bởi findings `system`, không phải `web`). - **Thiếu** → cảnh báo mềm (không chặn): ``` ⚠️ /review-context chưa chạy cho {uc-id}.feature. Khuyến nghị: chạy /review-context {feature-file} trước để kiểm chất lượng BDD. ``` - **Có** → kiểm các finding critical chưa xử lý với `status: "pending"`. Nếu có → **DỪNG** và in (các) feature vi phạm: ``` ❌ Cổng Chất lượng thất bại — {feature-file} Còn finding BDD critical chưa xử lý. Chạy: /review-context --fix {feature-file} ← auto-fix những gì có thể Rồi: /review-context --resume {feature-file} Rồi chạy lại: /generate-tech-docs {đúng các feature file đó} ``` 2. Đọc `# @trace.status:` của feature (tín hiệu duyệt chuẩn). Nếu feature nào ≠ `approved` → cảnh báo mềm (đồng bộ generate-code / qc-analyze): *"BDD {uc-id} chưa approved (@trace.status: {status}) — tech design dựng từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)"*. Cổng này chỉ chạy cho `input_features` (batch) — không bao giờ quét BDD ngoài cái tech lead trỏ vào. --- ## Bước 3 — Điều kiện tiên quyết Client (chỉ khi batch có feature `web/` hoặc `app/`) Các block client §4.5 (phân cấp component, map Figma → design-system, hình dạng state, test selector) được **suy ra** từ design spec. Định vị nó: - **Design Spec** — `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}*.md`. - **Tìm thấy** → nạp; Screen Specs / Component Inventory / Screen States của nó cấp cho §4.5 và mô hình state client ở §4.5.3. - **Không thấy** → cảnh báo mềm (không chặn cứng — các section backend vẫn giá trị đầy đủ, và §4.5 có thể draft chỉ-text từ client BDD, đánh dấu degraded): ``` ⚠️ Không tìm thấy design-spec cho {TICKET-ID}. §4.5 (map UI component, tham chiếu Figma, test selector) sẽ được draft chỉ từ BDD và đánh dấu "[DRAFT — no design-spec]". Chạy /generate-design-spec trước để đủ độ trung thực. Tiếp tục? (Y/N) ``` Cũng nạp, khi có, catalog Figma component (`figma-components/{module}.md`) và design token (đã nạp bởi context-loader Bước 6-B/6-C) để ưu tiên component trong catalog ở §4.5.1/§4.5.2 và token thật ở §4.5.5. > **Lưu ý:** vì BE và FE giờ nằm trong **cùng** một tài liệu, không còn cổng "BE contract phải tồn tại trước" — backend contract (§4) và client design (§4.5) được sinh cùng nhau. §4.5.4 vẫn yêu cầu mỗi client service method map tới một endpoint **thật** khai báo ở §4.1 (đừng bịa endpoint). --- ## Bước 4 — Kiểm tra Brownfield Đọc `@trace.api_source` ở header mỗi feature của batch, và kiểm bảng Metadata của PRD tìm `| **API Source** | existing |`. | Giá trị | Chế độ | |-------|------| | `existing` | **Reverse-document** — API đã tồn tại; mô tả as-is, ghi chú gap so với BDD, không thiết kế mới | | vắng / khác | **Greenfield** — thiết kế API từ scenario | Lưu `active_mode`. Nếu `reverse-document`, nạp appendix "Existing API Contract" từ PRD làm input cho §4. --- ## CHECKPOINT — Kế hoạch Tech Design Trước khi sinh, hiện kế hoạch và chờ **Y** rõ ràng: ``` Kế hoạch Tech Design — {TICKET-ID} (doc full-stack / PRD) ────────────────────────────────────────────────────── PRD : {TICKET-ID} — {feature title} Chế độ : {Fresh (doc mới) | Append (mở rộng doc có sẵn)} Batch : {M} file feature lần này: - {input_features[0]} ({platform} · UC{n} · {add-new|extend-platform|refresh}) - {…} Service : {trace.service} Module: {trace.module} Platform : {các platform trong batch} Chế độ API : {Reverse-document (API existing) | Greenfield (thiết kế mới)} Scenario : {N} scenario trong batch BDD ver : {bdd_version lớn nhất trong batch} Design-spec: {đã nạp | ⚠️ thiếu (§4.5 degraded) | n/a — batch không có feature client} UC của doc : đã phủ → {covered_ucs hoặc "chưa (doc mới)"}; lần này → {batch UCs} Output : {output_path} ({tạo | mở rộng}) Section sẽ {sinh | thêm} cho batch này: {backend (system trong batch): §1–§4.4, §6–§8} {client (web/app trong batch): §4.5 cho {platform}} §5 Key Flows — {N} sequence diagram trong lane platform (5.A system/5.B web/5.C app), mỗi cái tiêu đề "platform · SC" §9 Design Decisions (row mới) · §10 UC Coverage (khoá theo platform×SC) · §11 Cross-cutting · Changelog ────────────────────────────────────────────────────── Tiếp tục? (Y/N) ``` Chờ "Y" rõ ràng. --- ## Sinh Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội dung cho (các) UC** trong `input_features`. Điền các placeholder `{…}` liên quan và xoá các comment hướng dẫn khi làm. - Section **Backend** (§2–§4.4, §6–§8) đến từ feature `system/` trong batch (hoặc, brownfield, từ contract existing của PRD). - Block **Client** §4.5 đến từ feature `web/`·`app/` trong batch + design-spec. Dùng **cùng** giá trị test-id giữa web/app cho cùng một element logic (chỉ khác attribute theo platform). - **§5 Key Flows** — một mermaid sequence diagram cho mỗi scenario của batch, participant trải mọi tầng (client component → service → API → external API → DB). **Gom theo lane platform** (5.A system · 5.B web · 5.C app) và đặt tiêu đề mỗi diagram bằng **platform · SC** (vd `web · UC1-SC1`) — vì `{UC}-SC{N}` chỉ độc nhất trong (UC × platform): `system UC1-SC1` và `web UC1-SC1` là hai scenario khác nhau. Đừng bao giờ ghi trơ `UC1-SC1`. Chỉ tạo lane cho platform có BDD. - **§1/§2** (Overview/Actors, Architecture) là cấp PRD: viết ở lần chạy đầu; các lần sau chỉ mở rộng nếu batch thêm actor/integration thật sự mới. - **§10 UC Coverage** — một row UC (có cột Platforms) + bảng con coverage-scenario khoá theo **(platform, SC)** — mỗi platform×SC một row, vì cùng số SC ở platform khác nhau là scenario khác nhau. Đây là mỏ neo mà chế độ APPEND đọc. Luôn cập nhật nó cho (các) UC/platform của batch. **Chế độ APPEND (doc đã tồn tại):** **đừng** viết lại section có sẵn. Chèn diagram §5 của UC batch **vào đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối trong lane đó, tiêu đề `platform · SC`), các row mới ở §3/§4.3/§8/§9; với §4.5 — platform mới → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm (không lặp nhóm); rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog. Bump `@trace.revision` và làm mới `@trace.ucs` / `@trace.platforms` ở header, và cập nhật entry của platform vừa đụng trong map `@trace.bdd_version` (vd set `web=2.0`, giữ nguyên `system`). # {Feature Area} — {PRD Title} Technical Design Document --- @trace.id: {TICKET-ID} @trace.domain: {domain} @trace.prd: {TICKET-ID} @trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …} @trace.service: {service — from BDD header @trace.service} @trace.module: {module(s) involved — e.g. dotnet, angular} @trace.platforms: {system | web | app — whichever BDD folders exist} @trace.bdd_version: {per-platform map — e.g. system=1.5, web=1.9, app=1.7; only platforms present. Each feature carries its own bdd_version; do not flatten to one number.} @trace.api_source: {existing | —} @trace.revision: 1 @trace.status: draft @trace.generated_at: {YYYY-MM-DD} --- > **Related docs:** {link sibling PRDs / tech-designs this depends on, e.g. [OTHER-TICKET](../{other-slug}/tech-docs/{OTHER-TICKET}-tech-design.md)}. Delete if none. ## 1. Overview {What the feature does, its main actor, and the core technical mechanism. State which data is owned (DB) vs sourced live (external API), and the primary write.} ### Goals - {Goal 1} - {Goal 2} ### Business Actors | Actor | Description | Channel | |-------|-------------|---------| | {Actor} | {role & permission} | {entry path, e.g. App → Widget → Portal → API} | --- ## 2. Architecture Overview ### 2.1 High-level Architecture ``` {ASCII or mermaid diagram of the components this feature touches} ``` > **Note:** {call out which data is fetched live from an external API vs stored in the owned DB, and any cache layer + TTL.} ### 2.2 Communication Patterns | Pattern | Usage | Scope (UC/SC) | |---------|-------|---------------| | {Client → Gateway → API} | {auth / action} | {UC1} | | {API → External API} | {what it fetches, cache TTL} | {UC1-SC…} | --- ## 3. Data Model ### 3.1 Entity Design #### {EntityName} ({DB entity | API-sourced POCO}) {One line: what it represents, and whether it is persisted or fetched live.} | Field | Type | Usage in {TICKET-ID} | |-------|------|----------------------| | `{field}` | `{type}` | {how this feature uses it — read/write, which SC} | **State transitions (if any):** ``` {state A}: {condition} → {outcome / UI signal} {state B}: {condition} → {outcome} ``` **Constraints:** - {invariant enforced in application/DB logic, e.g. exactly one primary per tenant} ### 3.2 Entity Relationships ``` {relationship diagram — cardinalities, join keys, which fields are read-only vs owned} ``` ### 3.3 Data Source Boundaries **{TICKET-ID} scope: {READ … / WRITE …}.** | Responsibility | In scope? | Handled by | |----------------|-----------|-----------| | {read merged list} | ✅ Yes | {endpoint / service} | | {write X flag} | ✅ Yes | {service} | | {base data} | ❌ Read-only | {external API + cache} | | {other module concern} | ❌ No | {module/team} | ### 3.4 Multi-tenant & Sharding - {tenant key on entities, query-filter isolation, shard resolution — from architecture.md} --- ## 4. API Contracts ### 4.1 Endpoints ``` {METHOD} {/path} # NEW | REUSE ({source}) — {one-line purpose} ``` ### 4.2 Request/Response Models ```{lang} {DTO definitions with per-field source comments} ``` ### 4.3 Validation & Error Codes **Validation rules:** ```{lang} {validation rules, in the stack's idiom (e.g. FluentValidation / class-validator)} ``` | Code | HTTP Status | Description | Trace | |------|-------------|-------------|-------| | `{ERROR_CODE}` | {4xx/5xx} | {when it fires} | {UC1-SC…} | ### 4.4 Handler Logic (key endpoints) **{HandlerName}:** 1. {step} 2. {step — transaction boundary if any} ### 4.5 UI Component Mapping — {platform} ({framework}) > **Source:** {Figma file + node id, from design-spec} > **Stack:** {framework, state primitive, component library} > #### 4.5.1 Component Hierarchy — {Screen} ({UC}) ``` {component tree — container vs presentational, conditional children} ``` #### 4.5.2 Component File Mapping | Component | Path | Type | Purpose | |-----------|------|------|---------| | `{Component}` | `{path}` | {Feature/Child} | {responsibility} | #### 4.5.3 State Management ({state primitive}) ```{lang} {state declarations with source comments (which BDD field / BE field each maps to)} ``` #### 4.5.4 API Integration Layer (port/adapter) | Client method | Endpoint (§4.1) | Request map | Response → model | Error → UI | |---------------|-----------------|-------------|------------------|-----------| | {svc.getX()} | {GET /…} | {params} | {DTO → ViewModel} | {4xx → state/toast} | #### 4.5.5 Figma → Design System Mapping | Figma element | Design system class/token | Notes | |---------------|---------------------------|-------| | {element} | {class / token} | {size, color, state} | #### 4.5.6 Test Selectors — element IDs for actionable elements (QC contract) | Test-ID | Element | Component (§4.5.1.x) | Action | Serves SC (UC · SC) | |---------|---------|----------------------|--------|---------------------| | `{uc}-{screen}-{element}-{type}` | {Submit button} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} | --- ## 5. Key Flows (Sequence Diagrams) ### 5.A System flows #### 5.A.1 {name} (system · {UC}-SC…) ```mermaid sequenceDiagram participant {A} as {Actor} {…} ``` ### 5.B Web flows #### 5.B.1 {name} (web · {UC}-SC…) ```mermaid sequenceDiagram {…} ``` ### 5.C App flows #### 5.C.1 {name} (app · {UC}-SC…) ```mermaid sequenceDiagram {…} ``` **Key integration points (optional table per flow):** | Step | State transition | Verified by (platform · SC) | |------|------------------|-----------------------------| | {step} | {before → after} | {web · UC1-SC…} | --- ## 6. Integration Points | Integration | Direction | Method | Description | |-------------|-----------|--------|-------------| | {Client → API} | Outbound (client) | {REST/Bearer} | {what} | | {API → External} | Outbound (server) | {REST + header} | {what, cache TTL} | ### 6.1 Event Bus / Messaging {events, or N/A} ### 6.2 Cross-Service Dependencies | Dependent service | What's needed | Contract | Status | |-------------------|---------------|----------|--------| | {service} | {need} | {endpoint} | {✅ Exists / ⚠️ pending} | --- ## 7. Security & Authorization ### 7.1 Authentication {Auth flow + token type/TTL. Source: PRD auth + project rules.} ### 7.2 Authorization Rules | Action | Required role/permission | Description | Trace | |--------|--------------------------|-------------|-------| | {action} | {role} | {how enforced, where} | {UC1-SC… / out of scope} | --- ## 8. Error Handling & Edge Cases | Scenario | Strategy | Details | Trace | |----------|----------|---------|-------| | {condition} | {approach} | {behavior, message, side effect} | {UC1-SC…, BR…} | --- ## 9. Design Decisions | # | Decision | Rationale | Alternatives considered | |---|----------|-----------|-------------------------| | 1 | **{decision}** | {why} | {alt — why rejected} | ### NFR-to-Design Mapping | NFR category | PRD requirement | Design decision | |--------------|-----------------|-----------------| | {e.g. Multi-tenant isolation} | {requirement} | {mechanism} | --- ## 10. UC Coverage | UC | Feature | Platforms | Sections covered | Status | |----|---------|-----------|------------------|--------| | {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered | ### UC1 Scenario Coverage | Platform | Scenario | Section | Business rule | |----------|----------|---------|---------------| | system | {UC}-SC1: {name} | §5.A.1 | {BR…} | | web | {UC}-SC1: {name} | §4.5 (web), §5.B.1 | {BR…} | --- ## 11. Cross-cutting & Assumptions (Out-of-Scope Reference) ### 11.1 {Concern} > {Quote the BDD/PRD line that scopes it out.} {Explanation of the boundary + a reference sequence diagram if useful.} **Owned by:** {team / module}. See {link}. --- ## 12. GAP Register — ẩn số thiết kế chưa chốt | id | Dùng ở (§) | Điều chưa biết | Loại | Owner confirm | Severity | Status | Đóng thế nào | |----|-----------|----------------|------|---------------|----------|--------|--------------| | G1 | {§4.3} | {shape lỗi khi partner từ chối} | cross-service | {team-payment} | 🔴 blocker | open | {T7 sign-off — owner cung cấp contract} | | A1 | {§4.1} | {timeout mặc định 30s} | nội tại | {BE lead} | 🟢 non-blocker | open | {BE xác nhận, thay giá trị} | > Nếu doc **không có** ẩn số nào → ghi "Không có — mọi thiết kế đều có nguồn." **KHÔNG** bịa dòng để lấp trống. --- ## Figma Design References - {Screen}: [Figma — {frame}]({url}) - Exported: {YYYY-MM-DD} --- ## Changelog | Revision | Date | Changes | |----------|------|---------| | 1 | {YYYY-MM-DD} | Initial generation from {TICKET-ID} BDD (v{bdd_version}): {list UCs covered} | --- ## Self-Review Gate — REFUTE trước khi ghi *(bắt buộc; chạy cả Fresh lẫn Append)* Trước khi finalize/append doc, **tự phản biện bản nháp** qua 4 cổng dưới — không phải "sinh rồi tin", mà "sinh rồi ĐỐI CHIẾU với ngữ cảnh rộng hơn + khai GAP tường minh". Nguyên tắc nền: **Completeness ≠ Coverage** — "mọi SC được map" là *cần*, KHÔNG *đủ*; trung thành với lát BDD trước mặt không phải là đúng khi nó chỉ là một lát cắt. Cổng nào không đạt → **sửa, hoặc khai `[GAP]` / `[ASSUMPTION: {owner} confirm]` ngay tại chỗ trong doc** — TUYỆT ĐỐI không bỏ trắng, không bịa lặng. **Cổng 1 — RECONCILE (đối chiếu chéo, đọc-ngược CÓ GIỚI HẠN).** Đọc-ngược **bounded** — chỉ 3 nguồn này, KHÔNG kéo toàn bộ BDD của PRD (giữ batch nhỏ): - **PRD Business Rules** của UC → mọi BR có được §3/§4/§5 phản ánh? Nguồn/sự kiện nào BR yêu cầu mà doc thiếu → thêm, hoặc `[GAP]`. - **core-entities.md** → mỗi enum/trạng thái doc dùng có **producer** (ai sinh ra giá trị)? Mỗi cột/field có **writer** (luồng nào set)? Enum mồ côi / cột không writer → sửa hoặc flag. - **Seam UC anh em cùng domain** (chỉ endpoint/entity giao nhau) → không định nghĩa lại contract đã có ở UC khác; không tự mâu thuẫn enum mình vừa viết trong chính doc này. **Cổng 2 — GAP-or-FLAG (trung thực, không bịa).** Cần một type/giá trị/policy (auth, config, event, error code) mà **không có nguồn** → **không** chép hình dạng ở boundary, **không** bịa: ghi `[GAP]` hoặc `[ASSUMPTION: {owner} confirm]`. Nếu doc định thiết kế endpoint/flow mà **BDD không định nghĩa nghiệp vụ** (design vượt BDD) → khai GAP + escalate, đừng âm thầm hợp thức hoá. **Cổng 3 — CATALOG (không hard-code).** Literal & constant rải rác như luật → gom lại: **generic envelope** (đừng typed-per-thing khi PRD-BR đã đưa hợp đồng chung) + bảng catalog (vd `signal_type × source`) + constants **đặt tên**. Fail nếu còn hằng số/enum inline chưa vào catalog. **Cổng 4 — CROSS-SERVICE & COMPLETENESS.** - **Ranh giới:** không kéo định danh **nội bộ** service khác vào lookup của mình — dùng abstraction tầng mình. Tương tác 2 service: nói rõ **bên nào own dedup/ordering** + có **ack path** + cross-field invariant. > **Thuật ngữ (đọc nhanh):** > - **dedup** (khử trùng) — cùng một event/message tới **≥2 lần** thì chỉ được xử lý **một** lần (thường qua *idempotency key*). Thiếu → cộng đôi, ghi đôi. > - **ordering** (thứ tự) — event tới **đúng trình tự** phát ra; nếu có thể tới lệch thì chốt: bên nào sắp lại, hay bên nhận phải **chịu được** lệch. Thiếu → state sai (vd "hết hạn" xử lý trước "tạo mới"). > - **ack path** (đường xác nhận) — bên nhận xử lý xong **báo lại** bên gửi ("đã nhận/đã xử lý") để bên gửi ngừng gửi lại. Thiếu → mất event, hoặc gửi lại vô hạn. > - **cross-field invariant** — ràng buộc phải **luôn đúng** giữa nhiều field/entity (vd `tổng các phần = tổng`, `trạng thái = paid ⇒ paid_at ≠ null`). - **Không happy-only:** mỗi API/flow phải **xét đủ** nhánh happy + partial + error + rollback, kể cả khi BDD chỉ tả happy. Thiết kế nhánh lỗi **từ nguồn** (PRD-BR về xử lý thất bại · pattern rollback ở CLAUDE.md §2 · chuyển-trạng-thái entity ở core-entities). Chi tiết nào **không suy được từ nguồn** (error code/shape của service khác, quyết định retry-hay-fail…) → **khai `[GAP]`, KHÔNG bịa** (Cổng 2). *Bắt buộc CÓ nhánh lỗi ≠ bịa NỘI DUNG nhánh lỗi.* - **Đủ chi tiết hàm:** hàm cốt lõi tả **điều kiện chọn / nhánh / kết quả**, không dừng ở tên hàm + sequence-diagram. **Ghi sổ + cổng chặn (bắt buộc khi có GAP).** Mỗi `[GAP: Gn]`/`[ASSUMPTION: An]` khai inline PHẢI có đúng **một** dòng ở **§12 GAP Register** (không marker mồ côi), gán: - **Loại**: `nội tại` (BE tự quyết) · `cross-service` (team/partner khác — đóng qua T7 sign-off) · `spec-defect` (BDD/PRD sai → escalate PO, xem Conflict register dưới). - **Severity**: 🔴 `blocker` (code bắt buộc phải có mới đúng) · 🟢 `non-blocker` (đoán tạm chạy được, cần confirm). Nhãn GAP/ASSUMPTION **không** tự quyết severity — một ASSUMPTION vẫn có thể là blocker. - **Owner** phải confirm + **Status** = `open`. Nếu §12 còn **≥1 🔴 blocker `open`** → set `@trace.status: in-review` (KHÔNG để `approved`) — `generate-code` bị chặn tới khi đóng hết blocker. (Cùng pattern design-spec giữ `draft` khi còn ❌ Missing.) Nếu 0 ẩn số → §12 ghi "Không có", đừng bịa dòng. > **Conflict register:** nếu BDD **mâu thuẫn** một invariant kiến trúc (CLAUDE.md §2 / core-entities) → ghi vào §9 Design Decisions như **conflict cần PO sửa `.feature`** (và một dòng §12 loại `spec-defect`), KHÔNG tự quyết, KHÔNG lặng chép. > **Guardrail nguồn:** 4 cổng này phản chiếu `project-lessons` **L-012** (nếu project có) — nạp ở context-loader Bước 6.7 như ràng buộc cứng, sống sót qua `/update-framework`. Cổng ở đây là lớp framework; L-012 là lớp project-local; cả hai cùng hiệu lực. `/review-tech-docs` **T8/T9** bắt lại ở cổng review nếu gen bỏ lọt. Ghi số `[GAP]`/`[ASSUMPTION]` đã khai vào report Output. --- ## Công bố — chia sẻ doc (umbrella + spec repo dùng chung) Nếu `paths.tech_docs_dir` phân giải **dưới `setup.spec_source`** (vd `{spec_source}/specs/{domain}/{prd-slug}/tech-docs`), doc được ghi **bên trong spec submodule**. Công bố nó (commit 2 tầng) để cả team đọc qua `/sync` — tech design gộp per-PRD này là blueprint liên team (API contract cho BE, client design cho FE/App): ```bash cd {spec_source} git add {output_path} # {TICKET-ID}-tech-design.md git commit -m "docs({TICKET-ID}): full-stack technical design ({mode})" git push origin {spec_branch} # branch teammate theo dõi trong .gitmodules cd - git add {spec_source} && git commit -m "chore: bump spec pointer ({TICKET-ID} tech design)" ``` Nếu `tech_docs_dir` là **local** — tức không có `setup.spec_source` (single-repo, hoặc một BE repo đa-service thuần không có spec module dùng chung) — bỏ qua bước này; không cần publish liên-repo. ## Output # Report Footer — Định dạng output chuẩn cho mọi lệnh Mọi report của lệnh phải kết thúc bằng section footer chuẩn này. ## Status Badge Chọn một theo kết quả: - `✅ Complete` — mọi bước thành công, không có vấn đề - `❌ Failed` — lệnh không hoàn thành được do lỗi chặn - `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại ## Output Artifacts Liệt kê mọi file được tạo hoặc sửa bởi lệnh này: ``` Output Artifacts: {created|updated} {file-path} ({mô tả ngắn}) {created|updated} {file-path} ({mô tả ngắn}) ``` Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`. ## Pipeline Position In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`, để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end: ``` Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit ``` Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên: | Phase | Commands | |-------|----------| | Discovery | `/define-product` | | PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) | | Design Spec | `/generate-design-spec` | | BDD | `/generate-bdd` · `/review-context` (BDD) | | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` | | Code | `/generate-code` · `/review-code` | | Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` | | QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` | | Trace Audit | `/validate-traces` | Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd: `Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`. **Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`, `/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính — **bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ). ## Gợi ý lệnh tiếp theo Gợi ý lệnh kế tiếp hợp lý theo phase của workflow: | Lệnh hiện tại | Gợi ý lệnh tiếp theo | |-------------------------|-----------------------------------------------| | /setup-ai-first | `/define-product` để bắt đầu feature đầu tiên | | /define-product | `/generate-prd {product-definition-file}` | | /generate-prd | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` | | /refine-prd | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` | | /review-context (PRD) | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) | | /generate-design-spec | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` | | /generate-bdd | `/review-context {feature-file}` để kiểm tra độ phủ | | /review-context (BDD) | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX | | /qc-analyze | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) | | /qc-plan | `/qc-design-test {UC-ID}` | | /qc-design-test | `/qc-review {UC-ID}` (review test-case) | | /qc-review (test-case) | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX | | /qc-run-test | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) | | /qc-review (script) | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED | | /qc-report | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) | | /generate-tech-docs | `/review-tech-docs {tech-design-file}` | | /review-tech-docs | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX | | /generate-code | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` | | /dev-gen-test | `/dev-run-test {UC-ID}` | | /dev-run-test (passing) | `/review-code {UC-ID}` | | /dev-run-test (failing) | `/fix-bug {ticket-id}` hoặc `/debug {error}` | | /review-code | `/dev-smoke-test {UC-ID}` hoặc tạo PR | | /dev-smoke-test | Tạo PR và link tới ticket | | /validate-traces | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR | | /fix-bug | Tạo PR và link tới ticket | | /debug | `/fix-bug {ticket-id}` nếu cần sửa | | /report-bug | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` | | /propose-scenario | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` | | /learn | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp | | /sync | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu | | /update-framework | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án | Định dạng footer như sau: ``` --- Status : {badge} {khối Output Artifacts} Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume Next : {lệnh gợi ý kèm ví dụ tham số} ``` *(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)* ``` /generate-tech-docs hoàn tất — {TICKET-ID} (tech design full-stack, {mode}) File: {output_path} Lần này: {UC/platform của batch đã thiết kế} | Doc giờ phủ: {mọi UC trong §10} Self-review: {n} [GAP]/[ASSUMPTION] đã khai ← resolve/confirm với owner trước khi /review-tech-docs Next: /review-tech-docs {output_path} ← cần SA/Lead review trước khi sinh code → nếu sống trong spec repo dùng chung: commit + push spec submodule (xem Công bố ở trên) để teammate đọc qua /sync → sau khi approved: BE → /generate-code {system .feature} FE → /generate-code {web|app .feature} --phase=integration (wire API thật theo §4.5.4 của doc này) ```