@dtd-dev/agent-kb 0.1.0

package/template/AGENTS.md

@@ -0,0 +1,34 @@
+<!--PROJECT:{{PROJECT_NAME}}-->
+# AGENTS.md
+
+> File "cửa vào" chuẩn chung cho mọi AI agent (Codex, Cursor, Copilot, Gemini, Windsurf, Aider, Zed...).
+> Đây là NGUỒN CHÂN LÝ duy nhất. Các file CLAUDE.md / GEMINI.md / copilot-instructions.md chỉ trỏ về đây.
+> Mục tiêu: chỉ load đúng context cho từng task → tiết kiệm token.
+
+## Luôn load (Tier 1 — context lõi, giữ nhỏ)
+- `.ai/core/tech-stack.md`
+- `.ai/core/coding-standards.md`
+- `.ai/core/glossary.md`
+
+## Router: task → file cần đọc thêm (Tier 2, on-demand)
+| Khi bạn làm... | Đọc thêm |
+|---|---|
+| Tạo feature mới / sinh spec từ mô tả | `.ai/workflows/create-feature.md` + `.ai/specs/<feature>/` |
+| Fix bug | `.ai/workflows/fix-bug.md` + `.ai/memory/common-bugs.md` |
+| Rút kinh nghiệm / ghi bài học | `.ai/workflows/learn.md` + `.ai/memory/` |
+| Review code | `.ai/workflows/code-review.md` + `.ai/core/coding-standards.md` |
+| Release / deploy | `.ai/workflows/release.md` + `.ai/skills/devops/` |
+| Backend (trigger/on-call/request) | `.ai/skills/backend/*.md` |
+| Frontend (React/UI/Firebase) | `.ai/skills/frontend/*.md` |
+| Hiểu nghiệp vụ | `.ai/product/business-rules.md` + `.ai/product/domain-model.md` |
+| Hiểu kiến trúc / vì sao | `.ai/architecture.md` + `.ai/decisions/` |
+
+## Sub-agents
+- Định nghĩa sub-agent của dự án nằm ở `.ai/agents/*.md` (nguồn chân lý), đã emit sang `.claude/agents/` cho Claude Code.
+- Có sẵn: `reviewer`, `tester`, `bug-fixer`, `feature-builder` (mỗi agent tự trỏ về workflow/skill tương ứng).
+- Sửa ở `.ai/agents/` rồi chạy lại `agent-kb init` để đồng bộ; tạo agent mới: `agent-kb agent <tên>`.
+
+## Quy tắc
+- KHÔNG đọc toàn bộ `.ai/` — chỉ mở file khớp task.
+- Một nguồn chân lý là file này; đừng nhân bản rule sang file khác.
+- Prompt trực tiếp của người dùng ghi đè mọi rule ở đây.

package/template/CLAUDE.md

@@ -0,0 +1,4 @@
+@AGENTS.md
+
+<!-- Claude Code đọc file này. Dòng @import ở trên kéo toàn bộ AGENTS.md vào. -->
+<!-- Cần rule riêng cho Claude Code (vd 3-layer memory) thì thêm bên dưới, KHÔNG lặp lại nội dung AGENTS.md. -->

package/template/GEMINI.md

@@ -0,0 +1,6 @@
+# GEMINI.md
+
+@./AGENTS.md
+
+<!-- Gemini CLI đọc file này. Nếu phiên bản Gemini của bạn không hỗ trợ @import, -->
+<!-- mở settings.json và đặt: { "contextFileName": "AGENTS.md" } để đọc thẳng AGENTS.md. -->

package/template/_adr-skeleton.md

@@ -0,0 +1,8 @@
+<!-- Mục đích: 1 quyết định kiến trúc. -->
+# ADR-{{ADR_NUM}}: {{ADR_TITLE}}
+- **Trạng thái**: Proposed <!-- Proposed / Accepted / Superseded -->
+- **Ngày**: <!-- YYYY-MM-DD -->
+- **Bối cảnh**: <!-- vấn đề cần quyết -->
+- **Quyết định**: <!-- chọn gì -->
+- **Phương án loại bỏ**: <!-- và vì sao -->
+- **Hệ quả**: <!-- đánh đổi -->

package/template/_agent-skeleton.md

@@ -0,0 +1,21 @@
+---
+name: {{AGENT_NAME}}
+description: {{AGENT_DESC}}
+tools: {{AGENT_TOOLS}}
+---
+<!-- AI: điền nhiệm vụ & quy tắc từ mô tả người dùng + quy ước dự án. Mơ hồ thì HỎI. Điền xong xoá dòng này. -->
+
+Bạn là sub-agent **{{AGENT_NAME}}** của dự án này.
+
+## Trước khi làm
+- Đọc `AGENTS.md` (router) và **chỉ load file `.ai/` khớp task** — giữ context gọn, tiết kiệm token.
+
+## Nhiệm vụ
+- <!-- mô tả việc agent này làm -->
+
+## Quy tắc
+- Theo `core/coding-standards.md` và quy ước dự án.
+- <!-- ràng buộc riêng của agent -->
+
+## Tham chiếu
+- <!-- workflow/skill/spec liên quan trong .ai/ -->

package/template/_feature-skeleton/api.md

@@ -0,0 +1,8 @@
+<!-- Mục đích: hợp đồng API của feature. -->
+<!-- AI: điền theo convention ở examples/api-example.md; mã lỗi đặt tên máy đọc. Feature không có API thì để trống/xoá file. Mơ hồ thì HỎI. Điền xong xoá dòng này. -->
+# {{FEATURE_NAME}} — API
+## `<METHOD> /path`
+- Mô tả: <!-- ... -->
+- Request: <!-- ... -->
+- Response: <!-- ... -->
+- Lỗi: <!-- mã + ý nghĩa -->

package/template/_feature-skeleton/design.md

@@ -0,0 +1,6 @@
+<!-- Mục đích: thiết kế kỹ thuật của feature. -->
+<!-- AI: điền từ mô tả người dùng + domain-model.md/architecture.md. Quyết định lớn → đề xuất ADR. Mơ hồ thì HỎI, đừng bịa. Điền xong xoá dòng này. -->
+# {{FEATURE_NAME}} — Design
+- Tiếp cận: <!-- ... -->
+- Thay đổi data model: <!-- ... -->
+- Đánh đổi: <!-- ... -->

package/template/_feature-skeleton/requirements.md

@@ -0,0 +1,9 @@
+<!-- Mục đích: yêu cầu của feature. -->
+<!-- AI: điền các mục dưới từ mô tả của người dùng + business-rules.md/domain-model.md/glossary.md. Mơ hồ thì HỎI, đừng bịa. Điền xong xoá dòng này. -->
+# {{FEATURE_NAME}} — Requirements
+- Mục tiêu: <!-- ... -->
+- User story: Là <!-- vai trò -->, tôi muốn <!-- ... --> để <!-- ... -->
+- Acceptance criteria:
+  - [ ] <!-- ... -->
+- Ngoài phạm vi: <!-- ... -->
+- Business rules liên quan: <!-- BR-001, ... -->

package/template/_feature-skeleton/test-cases.md

@@ -0,0 +1,7 @@
+<!-- Mục đích: test case của feature. -->
+<!-- AI: phủ happy path + edge case + 1 ca cho mỗi BR liên quan ở requirements.md. Mơ hồ thì HỎI, đừng bịa. Điền xong xoá dòng này. -->
+# {{FEATURE_NAME}} — Test Cases
+| ID | Tình huống | Input | Kỳ vọng |
+|----|-----------|-------|---------|
+| TC-1 | <!-- happy path --> | | |
+| TC-2 | <!-- edge case --> | | |

package/template/_skill-skeleton.md

@@ -0,0 +1,16 @@
+<!-- Mục đích: <điền mục đích skill>. Load khi task thuộc loại này. -->
+<!-- AI: điền từ mô tả người dùng + code thật của dự án. Mơ hồ thì HỎI. Điền xong xoá dòng này. -->
+# Skill: {{SKILL_NAME}}
+
+## Khi nào dùng
+<!-- task nào kích hoạt skill này -->
+
+## Quy tắc / pattern
+- <!-- bước hoặc nguyên tắc 1 -->
+- <!-- bước 2 -->
+
+## Cạm bẫy thường gặp
+- <!-- lỗi hay mắc + cách tránh -->
+
+## Tham chiếu
+- <!-- link tới spec/ADR/example liên quan -->

package/template/_stacks/go.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: chuẩn code Go cho dự án. Load khi task đụng backend Go. -->
+# Stack: Go
+
+## Quy tắc / pattern
+- **Lỗi tường minh**: trả `error`, bọc ngữ cảnh bằng `fmt.Errorf("...: %w", err)`; kiểm tra ngay, không nuốt.
+- **`context.Context`** là tham số đầu cho I/O/handler; tôn trọng huỷ & timeout.
+- **Interface nhỏ, định nghĩa ở nơi dùng** (consumer side); trả struct cụ thể, nhận interface.
+- **Đồng thời an toàn**: goroutine phải có cách dừng; tránh rò; bảo vệ state dùng chung bằng mutex/channel; chạy test với `-race`.
+- **`defer`** để đóng resource (file, rows, body). Kiểm lỗi của `Close` khi quan trọng.
+- **Bố cục**: theo package theo domain, không "utils" khổng lồ; `internal/` cho code không export.
+- **Format/lint**: `gofmt`/`goimports`, `go vet`, golangci-lint. Không tranh luận style tay.
+
+## Cạm bẫy thường gặp
+- Bỏ qua `err` (`_ = f()`) → lỗi ẩn.
+- Bắt biến vòng lặp trong goroutine (trước Go 1.22) → dữ liệu sai.
+- `panic` cho lỗi nghiệp vụ — chỉ panic cho lỗi lập trình thật sự.
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/devops/docker.md`

package/template/_stacks/java.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: chuẩn code Java (Spring). Load khi task đụng backend Java. -->
+# Stack: Java
+
+## Quy tắc / pattern
+- **Immutability ưu tiên**: `final`, record cho DTO; tránh setter thừa.
+- **Dependency injection qua constructor** (không field injection); component nhỏ, một trách nhiệm.
+- **Lỗi**: exception nghiệp vụ riêng (kế thừa `RuntimeException` khi hợp lý); không nuốt; không log-and-rethrow lặp.
+- **`Optional`** cho giá trị có thể vắng ở API trả về; không dùng cho field/param.
+- **Tầng**: controller → service → repository; transaction ở service.
+- **Validate** bằng Bean Validation (`@Valid`) ở biên.
+- **Build/format**: Maven/Gradle ghim version; spotless/checkstyle; test JUnit5 + Mockito.
+
+## Cạm bẫy thường gặp
+- N+1 query với JPA (thiếu fetch join / `@EntityGraph`).
+- Trả entity JPA thẳng ra API (lộ field, lazy-loading exception) — dùng DTO.
+- `@Transactional` đặt sai tầng / gọi nội bộ cùng class không kích hoạt proxy.
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/devops/docker.md`

package/template/_stacks/node.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: chuẩn code Node.js/TypeScript backend. Load khi task đụng backend Node. -->
+# Stack: Node.js / TypeScript
+
+## Quy tắc / pattern
+- **TypeScript strict**: bật `strict`; tránh `any`, ưu tiên type/zod cho dữ liệu vào.
+- **async/await + xử lý lỗi**: không bỏ promise lửng; bọc lỗi có ngữ cảnh; tránh `throw` chuỗi — dùng class lỗi.
+- **Validate input ở biên** (zod/valibot) cho request/env; không tin dữ liệu ngoài.
+- **Cấu hình qua ENV** (12-factor); không hardcode; có schema kiểm tra env lúc khởi động.
+- **Tầng rõ ràng**: handler → service → repository; không nhét SQL vào controller.
+- **Không chặn event loop**: việc nặng → worker/queue; stream cho dữ liệu lớn.
+- **Tắt máy êm (graceful shutdown)**: bắt SIGTERM, đóng server/DB pool.
+
+## Cạm bẫy thường gặp
+- Quên `await` → lỗi nuốt mất, unhandled rejection.
+- Rò connection do không đóng pool/handle.
+- Log object vòng/secret ra console.
+
+## Tham chiếu
+- `core/coding-standards.md` · `examples/*` · `skills/devops/docker.md`

package/template/_stacks/php.md

@@ -0,0 +1,18 @@
+<!-- Mục đích: chuẩn code PHP (Laravel). Load khi task đụng backend PHP. -->
+# Stack: PHP
+
+## Quy tắc / pattern
+- **`declare(strict_types=1)`** + type hint đầy đủ; PHP hiện đại (8.x), tránh code kiểu cũ.
+- **Lỗi**: exception cụ thể, không `@` nuốt lỗi; tách lỗi nghiệp vụ vs hệ thống.
+- **Laravel**: validate qua Form Request; logic nặng ở Service/Action, controller mỏng; dùng Eloquent đúng (tránh N+1 bằng eager `with()`).
+- **Bảo mật**: query builder/Eloquent (chống SQL injection), `{{ }}` Blade tự escape, không tin input.
+- **Cấu hình qua `.env`/config**, không hardcode; không commit `.env`.
+- **Composer** ghim version; PSR-12; test PHPUnit/Pest; static analysis PHPStan/Larastan.
+
+## Cạm bẫy thường gặp
+- N+1 query do thiếu eager loading.
+- Nhồi logic vào controller/model "fat".
+- Mass-assignment không kiểm soát (`$fillable`/`$guarded`).
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/devops/docker.md`

package/template/_stacks/python.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: chuẩn code Python. Load khi task đụng backend/script Python. -->
+# Stack: Python
+
+## Quy tắc / pattern
+- **Type hints + mypy/pyright**; docstring ngắn cho hàm public.
+- **Virtualenv + lock** (uv/poetry/pip-tools); ghim version, không cài global.
+- **Lỗi tường minh**: bắt exception cụ thể, không `except:` trống; tạo exception nghiệp vụ riêng.
+- **Validate dữ liệu vào** bằng pydantic (API/config).
+- **f-string** cho format; **pathlib** cho đường dẫn; tránh mutable default argument (`def f(x=[])`).
+- **I/O & async**: dùng `async` đúng chỗ (web), không trộn blocking trong event loop.
+- **Format/lint**: ruff + black; `ruff check`, mypy trong CI.
+
+## Cạm bẫy thường gặp
+- Mutable default argument giữ state giữa các lần gọi.
+- `except Exception` nuốt cả lỗi lập trình.
+- Phụ thuộc thứ tự dict/đường dẫn tương đối khi chạy từ thư mục khác.
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/devops/docker.md`

package/template/_stacks/react.md

@@ -0,0 +1,20 @@
+<!-- Mục đích: chuẩn React/TypeScript frontend. Load khi task đụng UI React. -->
+# Stack: React
+
+## Quy tắc / pattern
+- **Function component + hooks**; một component một trách nhiệm, giữ nhỏ. Không class.
+- **Tách logic dùng lại ra custom hook** (`useXxx`); tuân rules-of-hooks (gọi ở top level).
+- **State đúng chỗ**: cục bộ `useState`; chia sẻ gần → lift up/context; **server state** dùng lib (React Query) — đừng nhồi vào global store.
+- **Data fetching**: xử lý đủ loading/error/empty; không fetch trong vòng render.
+- **`useEffect`** cho side-effect + cleanup; không dùng để tính giá trị dẫn xuất (tính khi render hoặc `useMemo`); dependency array đúng.
+- **Key danh sách** ổn định, không dùng index khi list đổi thứ tự.
+- **Tối ưu có đo lường**: `memo`/`useMemo`/`useCallback` chỉ khi cần.
+- **A11y**: thẻ ngữ nghĩa, `label` cho input, điều hướng bàn phím.
+
+## Cạm bẫy thường gặp
+- Sai/thiếu dependency `useEffect` → stale closure hoặc loop vô hạn.
+- Lạm dụng global state cho dữ liệu server → khó đồng bộ.
+- Mutate trực tiếp state/props.
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/frontend/ui-guideline.md`

package/template/_stacks/rust.md

@@ -0,0 +1,18 @@
+<!-- Mục đích: chuẩn code Rust. Load khi task đụng backend/CLI Rust. -->
+# Stack: Rust
+
+## Quy tắc / pattern
+- **Lỗi**: `Result<T, E>` + `?`; lib dùng `thiserror`, app dùng `anyhow`. Tránh `unwrap()/expect()` ngoài test/khởi tạo chắc chắn.
+- **Ownership rõ**: mượn (`&`/`&mut`) thay vì clone bừa; `clone()` có chủ đích.
+- **Type-state & enum** để biểu diễn trạng thái hợp lệ; tận dụng `match` đầy đủ nhánh.
+- **Async**: chọn một runtime (tokio); không block trong async; `Send + Sync` khi chia sẻ.
+- **Module**: chia theo domain; public API tối thiểu; `pub(crate)` khi nội bộ.
+- **Format/lint**: `cargo fmt`, `cargo clippy -D warnings`, test `cargo test`.
+
+## Cạm bẫy thường gặp
+- `unwrap()` trên dữ liệu ngoài → panic runtime.
+- Lạm dụng `clone()`/`Rc<RefCell>` để né borrow checker → che thiết kế sai.
+- `.await` giữ lock qua await point → deadlock/đình trệ.
+
+## Tham chiếu
+- `core/coding-standards.md` · `skills/devops/docker.md`

package/template/ai/README.md

@@ -0,0 +1,28 @@
+# .ai — Knowledge base cho AI agent
+
+Bản đồ context. AI đọc file này trước để biết **task → file cần load**, tránh nuốt cả thư mục.
+
+## Tầng context
+- **Tier 0 — Index**: file này.
+- **Tier 1 — Core (LUÔN load)**: `core/*.md`. Giữ mỗi file < ~500 token.
+- **Tier 2 — On-demand**: mọi thứ còn lại, chỉ đọc khi task đụng tới.
+
+## Loading rules (task → file)
+| Khi bạn làm... | Load thêm |
+|---|---|
+| Tạo feature mới / sinh spec từ mô tả | `workflows/create-feature.md` + `specs/<feature>/` |
+| Fix bug | `workflows/fix-bug.md` + `memory/common-bugs.md` |
+| Rút kinh nghiệm / ghi bài học | `workflows/learn.md` + `memory/` |
+| Review code | `workflows/code-review.md` + `core/coding-standards.md` |
+| Release / deploy | `workflows/release.md` + `skills/devops/` |
+| Backend task (trigger, on-call, request) | `skills/backend/*.md` |
+| Frontend task (React, UI, Firebase) | `skills/frontend/*.md` |
+| Hiểu nghiệp vụ | `product/business-rules.md` + `product/domain-model.md` |
+| Hiểu kiến trúc / vì sao thiết kế vậy | `architecture.md` + `decisions/` |
+
+**Nguyên tắc:** không đọc file không khớp task. Nghi ngờ thì hỏi, đừng load thừa.
+
+## Quy ước viết file
+- 1 file = 1 nhiệm vụ. Phình to → tách hoặc đẩy xuống Tier 2.
+- Tránh trùng lặp giữa các file (mỗi lần trùng = đốt token thừa).
+- Đầu mỗi file ghi 1 dòng mục đích để AI quyết định có cần đọc không.

package/template/ai/agents/bug-fixer.md

@@ -0,0 +1,23 @@
+---
+name: bug-fixer
+description: Tái hiện, tìm root cause và sửa bug theo quy trình dự án. Dùng khi có lỗi cần điều tra & vá.
+tools: Read, Edit, Bash, Grep, Glob
+---
+
+Bạn là **bug-fixer** của dự án này. Mục tiêu: sửa **đúng nguyên nhân gốc**, không vá triệu chứng.
+
+## Trước khi sửa
+- Đọc `AGENTS.md` (router); load `workflows/fix-bug.md`, `memory/common-bugs.md`, `memory/troubleshooting.md`.
+
+## Quy trình (bám `workflows/fix-bug.md`)
+1. **Tái hiện** ổn định; ghi bước + môi trường + kỳ vọng vs thực tế.
+2. **Tra** `memory/common-bugs.md` xem đã gặp chưa.
+3. **Khoanh vùng** → tìm **root cause** (hỏi "vì sao" tới gốc).
+4. **Viết test bắt bug trước** (fail), rồi sửa cho xanh (regression test).
+5. **Sửa tối thiểu** đủ giải quyết gốc; rà nơi khác cùng pattern.
+6. **Xác minh** lại bước tái hiện + test liên quan.
+7. Nếu đáng nhớ → đề xuất thêm vào `memory/common-bugs.md` (theo `workflows/learn.md`).
+
+## Lưu ý
+- Bug production gấp → giảm thiểu trước theo `workflows/incident-response.md`, sửa gốc sau.
+- Không xoá test/giảm assertion để qua.

package/template/ai/agents/feature-builder.md

@@ -0,0 +1,18 @@
+---
+name: feature-builder
+description: Dựng tính năng mới theo spec & chuẩn dự án (spec-first). Dùng khi triển khai một feature từ yêu cầu.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+Bạn là **feature-builder** của dự án này. Mục tiêu: làm đúng yêu cầu, theo spec, không phá tính năng cũ.
+
+## Trước khi code
+- Đọc `AGENTS.md` (router); load `workflows/create-feature.md`, `specs/<feature>/`, `core/coding-standards.md`, và skill liên quan trong `skills/`.
+- Chưa có spec? Tạo khung `agent-kb feature <tên>` và sinh spec theo `workflows/create-feature.md`; **yêu cầu mơ hồ thì HỎI, đừng đoán**.
+
+## Quy trình (bám `workflows/create-feature.md`)
+1. Hiểu yêu cầu (requirements.md) → 2. Thiết kế (design.md, ADR nếu lớn) → 3. Chốt API (api.md) →
+4. Code theo chuẩn + skill, commit nhỏ → 5. Test theo `test-cases.md` (happy + biên + business rule) → 6. Tự review (giao `reviewer`).
+
+## Definition of Done
+- Đủ acceptance criteria; test xanh có cả ca lỗi; cập nhật doc (spec/ADR/glossary); không secret/log debug sót.

package/template/ai/agents/reviewer.md

@@ -0,0 +1,20 @@
+---
+name: reviewer
+description: Review code thay đổi theo chuẩn & nghiệp vụ của dự án. Dùng sau khi viết xong một phần, trước khi mở PR.
+tools: Read, Grep, Glob, Bash
+---
+
+Bạn là **reviewer** của dự án này. Mục tiêu: bắt lỗi chặn merge trước, góp ý chất lượng sau — không tự ý sửa code.
+
+## Trước khi review
+- Đọc `AGENTS.md` (router) và chỉ load file `.ai/` khớp: `workflows/code-review.md`, `core/coding-standards.md`, và `specs/<feature>/` nếu liên quan.
+- Xem diff thật (vd `git diff`), không đoán.
+
+## Cách review (bám `workflows/code-review.md`)
+- **P0 (phải sửa)**: đúng acceptance criteria; correctness & edge case; bảo mật (secret/inject/phân quyền); có test cho logic mới.
+- **P1 (nên sửa)**: error handling, đồng thời/transaction/idempotency, hiệu năng (N+1), tương thích API/migration.
+- **P2 (chất lượng)**: tên rõ, hàm nhỏ, không lặp/magic value, không code chết/log debug.
+
+## Đầu ra
+- Gom theo P0/P1/P2; mỗi mục: vị trí (`file:line`) + lý do + gợi ý sửa. Tách "bắt buộc" vs "nit". Khen điểm tốt khi xứng đáng.
+- KHÔNG chỉnh sửa file — chỉ báo cáo.

package/template/ai/agents/tester.md

@@ -0,0 +1,21 @@
+---
+name: tester
+description: Viết và chạy test theo quy ước dự án. Dùng khi cần phủ test cho code mới hoặc bổ sung ca thiếu.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+Bạn là **tester** của dự án này. Mục tiêu: phủ test có ý nghĩa, không chạy theo coverage hình thức.
+
+## Trước khi viết test
+- Đọc `AGENTS.md` (router); load `examples/testing-example.md`, `core/coding-standards.md`, và `specs/<feature>/test-cases.md` nếu có.
+- Dùng đúng test runner/quy ước sẵn có của repo (xem `core/tech-stack.md`).
+
+## Nguyên tắc
+- Tên test mô tả **hành vi**, cấu trúc **arrange–act–assert**.
+- Phủ: happy path + ca lỗi/biên + **một ca cho mỗi business rule** liên quan (BR-00x).
+- Không xoá/nới lỏng assertion để "qua bài"; test phải fail khi logic sai.
+
+## Quy trình
+1. Liệt kê ca cần test (từ `test-cases.md`/yêu cầu).
+2. Viết test, chạy, đảm bảo xanh và thực sự kiểm đúng hành vi.
+3. Báo cáo: đã thêm ca nào, ca nào còn thiếu/không test được và vì sao.

package/template/ai/architecture.md

@@ -0,0 +1,40 @@
+<!-- Mục đích: kiến trúc tổng thể + luồng dữ liệu. Load khi cần hiểu hệ thống, không phải mỗi task. -->
+<!-- Đây là MẪU theo dự án CarePay (Firebase). Thay bằng kiến trúc thật của dự án bạn. -->
+# Architecture
+
+## Sơ đồ tổng thể
+```
+                ┌──────────────────────────┐
+   Người dùng → │  Web app (React + Vite)  │
+                └────────────┬─────────────┘
+                             │ Firebase SDK (Auth token đính kèm mỗi request)
+              ┌──────────────┼────────────────────────────┐
+              ▼              ▼                             ▼
+       Firebase Auth   Cloud Functions Gen2          Firestore (đọc trực tiếp
+       (đăng nhập)     ├─ onRequest  (HTTP API)      qua security rules cho
+                       ├─ onCall     (callable)      dữ liệu của chính user)
+                       └─ trigger    (Firestore/PubSub event)
+                             │
+              ┌──────────────┼──────────────┐
+              ▼              ▼               ▼
+          Firestore    Payment Gateway   Pub/Sub
+          (nguồn dữ    (đối tác ngoài)   (việc nền/
+           liệu chính)                    bất đồng bộ)
+```
+
+## Luồng dữ liệu chính (ví dụ: thanh toán viện phí)
+1. **Request đến**: client gọi callable `createPayment` (onCall) kèm Auth token.
+2. **Qua service**: function xác thực token → kiểm tra business rule → gọi Payment Gateway → ghi `payments/{id}` (status `pending`) vào Firestore.
+3. **Xử lý nền**: gateway gọi webhook (onRequest) báo kết quả → cập nhật `payments/{id}.status`. Một **Firestore trigger** trên thay đổi đó cập nhật số dư `wallets/{uid}` và bắn thông báo.
+4. **Phản hồi**: client lắng nghe (`onSnapshot`) tài liệu payment → UI cập nhật realtime.
+
+## Ranh giới (boundaries)
+- **Client KHÔNG** chứa secret / logic tính phí / ghi trực tiếp `payments` — mọi mutation tiền bạc đi qua Cloud Functions.
+- **onCall**: thao tác cần đăng nhập, gọi từ app. **onRequest**: webhook/đối tác ngoài (tự verify chữ ký). **trigger**: hệ quả phụ (cập nhật số dư, gửi mail) — KHÔNG để client gọi.
+- **Firestore Security Rules** là lớp phòng thủ cuối: client chỉ đọc dữ liệu của chính mình; ghi tiền bạc bị chặn ở rules.
+- **Idempotency**: webhook & trigger phải chịu được gọi lặp (dùng key giao dịch) — xem `decisions/ADR-002-cache.md` và business rules.
+
+## Liên kết
+- Quyết định kiến trúc & vì sao → `decisions/`
+- Thực thể & quan hệ → `product/domain-model.md`
+- Cách viết từng loại function → `skills/backend/*`

package/template/ai/core/coding-standards.md

@@ -0,0 +1,28 @@
+<!-- Mục đích: quy tắc clean code áp dụng mọi nơi. Quy tắc, không phải ví dụ (ví dụ ở examples/). -->
+# Coding Standards
+
+## Naming
+- Theo convention của ngôn ngữ (vd JS/TS: biến/hàm `camelCase`, type/class `PascalCase`, hằng `UPPER_SNAKE`).
+- Tên nói rõ ý định; tránh viết tắt mơ hồ và tiền tố thừa.
+
+## Hàm & module
+- Một hàm làm một việc; giữ ngắn (ưu tiên < ~30 dòng).
+- Tránh nesting sâu — dùng early return.
+- Không magic number/string — đặt tên hằng.
+- Tách side-effect khỏi logic thuần để dễ test.
+
+## Error handling
+- Không nuốt lỗi im lặng; log có ngữ cảnh (đủ để debug, không lộ dữ liệu nhạy cảm).
+- Tách rõ lỗi nghiệp vụ vs lỗi hệ thống.
+- Validate input ở biên (boundary), tin tưởng dữ liệu bên trong.
+
+## Comment & docs
+- Comment giải thích "vì sao", không lặp "cái gì". Code tự diễn đạt được thì bỏ comment thừa.
+
+## Test
+- Logic nghiệp vụ phải có test; phủ cả happy path lẫn ca lỗi/biên.
+- Tên test mô tả hành vi, không mô tả tên hàm.
+
+## Format & Git
+- Theo formatter/linter của repo (<!-- vd: Prettier+ESLint / gofmt -->); không tranh luận style thủ công.
+- Commit nhỏ, message theo <!-- vd: Conventional Commits -->.

package/template/ai/core/glossary.md

@@ -0,0 +1,20 @@
+<!-- Mục đích: thuật ngữ kỹ thuật + nghiệp vụ (đã gộp glossary & terminology). 1 dòng/khái niệm. -->
+<!-- Hàng dưới là MẪU theo dự án CarePay. Xoá/sửa theo thuật ngữ thật của dự án bạn. -->
+# Glossary
+
+> Gộp thuật ngữ kỹ thuật và nghiệp vụ vào một nơi để tránh trùng lặp.
+
+| Thuật ngữ | Nghĩa |
+|---|---|
+| CarePay | Nền tảng giúp bệnh nhân thanh toán viện phí (gồm trả góp) cho cơ sở y tế. |
+| Provider | Cơ sở y tế (bệnh viện/phòng khám) nhận thanh toán. |
+| Wallet | Số dư & lịch sử giao dịch của một người dùng (`wallets/{uid}`). |
+| Payment | Một lần thanh toán cho Provider; có vòng đời `pending → succeeded/failed`. |
+| Installment | Kế hoạch trả góp: chia một Payment thành nhiều kỳ. |
+| Gen2 | Cloud Functions thế hệ 2 (chạy trên Cloud Run) — chuẩn backend của dự án. |
+| Request (fn) | Function `onRequest` — endpoint HTTP, dùng cho webhook/đối tác ngoài. |
+| On-call (fn) | Function `onCall` — callable, gọi từ app đã đăng nhập (tự verify Auth). |
+| Trigger (fn) | Function chạy theo sự kiện (Firestore/Auth/Pub/Sub) — xử lý hệ quả phụ. |
+| Idempotency key | Khoá để một thao tác gọi lặp không tạo hiệu ứng kép (vd webhook trùng). |
+
+**Quy ước:** thêm từ mới vào đây thay vì giải thích lại trong nhiều file.

package/template/ai/core/tech-stack.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: stack + version. Chỉ liệt kê, KHÔNG giải thích. Giữ thật ngắn. -->
+# Tech Stack — {{PROJECT_NAME}}
+
+## Backend
+- {{BACKEND}}
+- Database: {{DATABASE}}
+- Cache / Queue: <!-- vd: Redis 7 -->
+
+## Frontend
+- {{FRONTEND}}
+- State: <!-- vd: Zustand / Redux Toolkit -->
+- UI: <!-- vd: Tailwind + shadcn/ui -->
+
+## Infra / DevOps
+- Container: <!-- vd: Docker -->
+- CI/CD: {{CICD}}
+
+## Quy tắc version
+- Không nâng major version nếu chưa ghi vào decisions/.

package/template/ai/decisions/ADR-001-auth.md

@@ -0,0 +1,9 @@
+<!-- Mục đích: 1 quyết định kiến trúc. Copy file này cho ADR mới. -->
+<!-- Nội dung dưới là MẪU (CarePay). Thay bằng quyết định thật của dự án bạn. -->
+# ADR-001: Xác thực bằng Firebase Auth + ID token
+- **Trạng thái**: Accepted
+- **Ngày**: 2024-01-15
+- **Bối cảnh**: Cần xác thực người dùng cho web app và bảo vệ Cloud Functions; team nhỏ, không muốn tự vận hành hệ thống auth/quản lý mật khẩu.
+- **Quyết định**: Dùng **Firebase Auth**. Client lấy ID token, đính kèm mỗi request. `onCall` tự verify token; `onRequest` verify thủ công qua Admin SDK. Phân quyền theo `uid` + custom claims (vd `role: admin`).
+- **Phương án loại bỏ**: Tự xây JWT + bảng user (tốn công, dễ sai về bảo mật); Auth0 (chi phí & thêm nhà cung cấp ngoài hệ Firebase đang dùng).
+- **Hệ quả**: Phụ thuộc Firebase; phân quyền phức tạp phải dùng custom claims (cần refresh token sau khi đổi claim); test cần Auth emulator.

package/template/ai/decisions/ADR-002-cache.md

@@ -0,0 +1,9 @@
+<!-- Mục đích: 1 quyết định kiến trúc. Copy file này cho ADR mới. -->
+<!-- Nội dung dưới là MẪU (CarePay). Thay bằng quyết định thật của dự án bạn. -->
+# ADR-002: Idempotency cho thanh toán & webhook
+- **Trạng thái**: Accepted
+- **Ngày**: 2024-02-02
+- **Bối cảnh**: Client/đối tác có thể retry; webhook gateway gửi lại nhiều lần. Nếu xử lý trùng sẽ double-charge hoặc cộng số dư hai lần.
+- **Quyết định**: Mỗi `createPayment` mang **idempotency key**; lưu key vào document `idempotency/{key}` và dùng **Firestore transaction** để "tạo nếu chưa có". Webhook khớp theo `gatewayRef` và chỉ chuyển trạng thái theo BR-003 (no-op nếu đã ở đích).
+- **Phương án loại bỏ**: Redis/Memorystore làm khoá idempotency (thêm hạ tầng & chi phí, chưa cần ở quy mô hiện tại); khử trùng ở tầng app sau khi ghi (có khe hở race).
+- **Hệ quả**: Mỗi mutation tiền bạc tốn thêm 1 lượt đọc/ghi khoá; logic phải bọc trong transaction; cần dọn document idempotency cũ theo TTL.

package/template/ai/decisions/ADR-003-logging.md

@@ -0,0 +1,9 @@
+<!-- Mục đích: 1 quyết định kiến trúc. Copy file này cho ADR mới. -->
+<!-- Nội dung dưới là MẪU (CarePay). Thay bằng quyết định thật của dự án bạn. -->
+# ADR-003: Structured logging + correlation ID
+- **Trạng thái**: Accepted
+- **Ngày**: 2024-02-20
+- **Bối cảnh**: Một thanh toán đi qua nhiều function (onCall → gateway → webhook → trigger); log dạng text rời rạc khó lần theo một giao dịch khi điều tra sự cố.
+- **Quyết định**: Log **JSON có cấu trúc** ra stdout (Cloud Logging tự thu). Mỗi log mang `correlationId` (= `paymentId` hoặc request id) xuyên suốt các function; gồm `severity`, `event`, `uid`. **Cấm** log dữ liệu nhạy cảm (token, số thẻ, PII).
+- **Phương án loại bỏ**: Log text tự do (khó query/đối soát); gửi sang dịch vụ log bên thứ ba (chưa cần, tốn chi phí).
+- **Hệ quả**: Phải truyền `correlationId` qua các lớp; cần helper log chung để đồng nhất field; có checklist review chặn việc log PII (xem `workflows/code-review.md`).

package/template/ai/examples/api-example.md

@@ -0,0 +1,31 @@
+<!-- Mục đích: mẫu request/response API chuẩn của dự án. -->
+# API Example
+
+> Mẫu REST theo convention mặc định (JSON). Đổi theo chuẩn thật của dự án nếu khác.
+
+## `POST /api/v1/accounts/{id}/withdraw`
+Rút tiền khỏi tài khoản.
+
+**Request**
+```json
+{ "amount": 50000 }
+```
+
+**Response 200**
+```json
+{ "accountId": "acc_123", "balance": 150000 }
+```
+
+**Lỗi** — body lỗi nhất quán: `code` (máy đọc) + `message` (người đọc).
+```json
+{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "Số dư không đủ" } }
+```
+
+| HTTP | code | Khi nào |
+|---|---|---|
+| 400 | `VALIDATION_ERROR` | Input sai (amount <= 0) |
+| 401 | `UNAUTHORIZED` | Thiếu/sai token |
+| 404 | `ACCOUNT_NOT_FOUND` | Không có tài khoản |
+| 409 | `INSUFFICIENT_BALANCE` | Số dư không đủ |
+
+**Convention**: path dùng danh từ số nhiều; version trong path (`/v1`); HTTP status đúng ngữ nghĩa; không lộ stack trace ra response.

package/template/ai/examples/coding-example.md

@@ -0,0 +1,28 @@
+<!-- Mục đích: minh hoạ chuẩn code (load khi cần "mẫu để bắt chước"). -->
+# Coding Example
+
+> Mẫu theo stack mặc định **TypeScript** — minh hoạ `core/coding-standards.md`.
+> Đổi sang ngôn ngữ thật của dự án nếu khác.
+
+Tên rõ nghĩa · early return · tách lỗi nghiệp vụ/hệ thống · hàm nhỏ, không magic value.
+
+```ts
+// Lỗi nghiệp vụ tách khỏi lỗi hệ thống để caller xử lý khác nhau.
+class InsufficientBalanceError extends Error {}
+
+const MIN_WITHDRAWAL = 1; // đặt tên hằng, không magic number
+
+interface Account { id: string; balance: number; }
+
+/** Rút tiền khỏi tài khoản. Trả về số dư mới. */
+export function withdraw(account: Account, amount: number): number {
+  // Validate ở biên, early return thay vì nesting sâu.
+  if (amount < MIN_WITHDRAWAL) {
+    throw new RangeError(`amount must be >= ${MIN_WITHDRAWAL}`);
+  }
+  if (amount > account.balance) {
+    throw new InsufficientBalanceError(`balance ${account.balance} < ${amount}`);
+  }
+  return account.balance - amount;
+}
+```