diff --git a/CLAUDE.md b/CLAUDE.md index 9b67df1..0d7d77c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -56,7 +56,19 @@ Kiến trúc: **.NET 10 Clean Architecture + 2 React FE (admin + user) + SQL Ser [CLAUDE] : ``` -**Scope:** `Contract` · `Form` · `Workflow` · `Supplier` · `Auth` · `Admin` · `Api` · `App` · `Domain` · `Infra` · `FE-Admin` · `FE-User` · `Docs` · `CICD` · `Scripts` +**Scope:** `Contract` · `Form` · `Workflow` · `Supplier` · `Auth` · `Admin` · `Api` · `App` · `Domain` · `Infra` · `FE-Admin` · `FE-User` · `Docs` · `CICD` · `Scripts` · `Skill` + +## 🛠️ Skills (.claude/skills/) — 6 skill PHẢI dùng khi task khớp + +| Domain (3) | Ops (3) | +|---|---| +| `contract-workflow` — state machine + versioned WF | `dependency-audit-erp` — npm/dotnet CVE scan | +| `form-engine` — render docx/xlsx + PDF | `ef-core-migration` — EF migration + 3-file rule | +| `permission-matrix` — role × menu × CRUD | `iis-deploy-runbook` — 3 site IIS + win-acme + runner | + +**Audit định kỳ:** đầu mỗi tháng — workflow `docs/rules.md §9.4`. Lần kế: **2026-05-01**. + +Quy tắc: KHÔNG bulk-clone repo skill 3rd party. Chỉ thêm skill PROJECT-SPECIFIC. Xem `docs/rules.md §9` đầy đủ. ## 📖 Tài liệu quan trọng diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index f2c233a..b58be2a 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -80,6 +80,18 @@ Login: `admin@solutionerp.local` / `Admin@123456` 3. **Rotate credentials** — SA SQL password, vrapp password, JWT secret prod, Gitea runner registration token 4. **Schedule SQL backup** — `schtasks /create /tn "SolutionErp Backup" /tr "powershell -File C:\...\scripts\backup-sql.ps1" /sc DAILY /st 03:00` +### A1. Định kỳ — Skill audit + +**Cadence:** Mỗi đầu tháng (4 tuần). Lần audit kế tiếp: **2026-05-01**. + +Workflow xem `docs/rules.md §9.4`. Tóm tắt: +1. Cross-check 6 skill hiện có với STATUS / gotchas / migration-todos +2. Check repo nguồn 3rd party (alirezarezvani/claude-skills) có gì mới +3. Update / archive / add skill nếu cần +4. Log vào `docs/changelog/skill-audit-2026-05.md` + +Trigger: user nói "audit skill" hoặc tự chạy đầu Phase mới. + ### B. Polish iterations (optional — khi UAT phát sinh) - **Roles CRUD** — admin tạo custom role ngoài 12 hardcoded (`Domain.Identity.AppRoles`) diff --git a/docs/changelog/migration-todos.md b/docs/changelog/migration-todos.md index 3ef7ba5..79a7988 100644 --- a/docs/changelog/migration-todos.md +++ b/docs/changelog/migration-todos.md @@ -243,6 +243,16 @@ - [ ] Dependencies scan vào CI (`dotnet list package --vulnerable --include-transitive`, `npm audit --audit-level=high`) - [ ] BE Roles CRUD (Create/Rename/Delete custom role) + FE `/system/roles` — optional, 12 role seed đủ dùng +## Skill governance (recurring) + +**Quy tắc:** xem `docs/rules.md §9`. Audit định kỳ mỗi đầu tháng — workflow §9.4. + +- [x] **Setup ban đầu** — 6 skill (3 domain + 3 ops), rules §9, HANDOFF section A1 ← `661f859`+ +- [ ] **Audit 2026-05-01** — log `docs/changelog/skill-audit-2026-05.md` +- [ ] **Audit 2026-06-01** +- [ ] **Audit 2026-07-01** +- [ ] (lập lại mỗi tháng đầu) + ## Tier 3 ERP (Session 2026-04-22) — feature-complete - [x] **Attachment upload E2E** — IFileStorage + CQRS + FE drag-drop (gotcha path-traversal) — `c8d0070` diff --git a/docs/rules.md b/docs/rules.md index c89211e..1bf8589 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -291,10 +291,104 @@ Co-Authored-By: Claude Opus 4.7 (1M context) - Audit log: mọi ghi phải log qua `ContractApproval` hoặc `AuditLog` (future) - Rate limit: `/api/auth/login` 5 req/min/IP (chưa implement — Phase 5) -## 9. Liên quan +## 9. Skills (.claude/skills/) + +> Project-level skills encode kiến thức SOLUTION_ERP-specific. Claude tự auto-invoke qua Skill tool dựa trên semantic match với `description` trong `SKILL.md`. **PHẢI dùng skill khi gặp task tương ứng — không tự suy luận lại.** + +### 9.1 Skills hiện có (6) + +**Domain (3) — logic nghiệp vụ:** + +| Skill | Trigger khi | +|---|---| +| `contract-workflow` | Bug chuyển phase, 403, mã HĐ sai, versioned WF, "HĐ cũ giữ cũ" | +| `form-engine` | Render template docx/xlsx, FieldSpec, PDF export, upload form mới | +| `permission-matrix` | Permission denied, gán role, menu không hiện, inherit Contracts/Workflows | + +**Ops (3) — devops + security + schema:** + +| Skill | Trigger khi | +|---|---| +| `dependency-audit-erp` | `npm audit`, `dotnet vulnerable`, scan CVE, nâng cấp package | +| `ef-core-migration` | `migrations add`, schema change, snapshot lỗi, revert migration, DesignTimeDbContextFactory | +| `iis-deploy-runbook` | Prod 500/502, cert hết hạn, restart app pool, gitea-runner fail, SignalR 401 | + +### 9.2 Nguyên tắc tạo skill mới + +**Project-specific, KHÔNG clone generic.** User-level skills global đã có sẵn (`code-reviewer`, `sql-database-assistant`, `focused-fix`, `senior-frontend`, `mcp-builder`, `webapp-testing`, `review`, `security-review`, ...). Project-level skills chỉ thêm khi: + +- Encode kiến thức **SOLUTION_ERP-only** (path, version pin, gotcha number, commit convention) +- Generic skill không thể có (vd: 8 migration history cụ thể của project) +- Có YAML `when-to-use` triggers rõ ràng (cả tiếng Việt + Anh) +- Workflow Vietnamese-first (audience là dev Việt) + +### 9.3 Format bắt buộc `SKILL.md` + +```markdown +--- +name: kebab-case-name +description: 1-3 câu mô tả + stack specificity (cho semantic match đúng) +when-to-use: + - "trigger english" + - "trigger tiếng Việt" +--- + +# Skill Name + +## Context +## Workflow / Commands (copy-pastable, không pseudocode) +## Pitfalls +## Code pointers (path đầy đủ src/Backend/...) +## Related (dẫn chiếu gotcha #N, docs/...) +``` + +### 9.4 Audit định kỳ — mỗi 4 tuần + +**Cadence:** Mỗi đầu tháng (hoặc thứ Hai tuần đầu tháng), chạy audit skill list: + +``` +1. Đọc .claude/skills/README.md — list 6 skill hiện có +2. Cross-check với: + - docs/STATUS.md "Recently Done" — feature mới nào chưa có skill cover? + - docs/gotchas.md — gotcha mới (>3 dòng) nào nên gom thành skill mới? + - migration-todos.md "In Progress" / "Next up" — task lớn sắp tới có cần skill? +3. Check repo nguồn skill 3rd party có gì mới: + - https://github.com/alirezarezvani/claude-skills (default-branch) + - Anthropic skills built-in (xem system reminder skill list) +4. Đánh giá staleness: + - Mỗi skill: SKILL.md có còn match code thực tế không? + - Trigger phrases có còn hiệu quả? + - Code pointers có còn đúng path? +5. Hành động: + - Skill stale → update SKILL.md + commit `[CLAUDE] Skill: refresh ` + - Skill cần thêm → tạo theo §9.2 §9.3 + commit `[CLAUDE] Skill: add ` + - Skill không còn cần → archive vào .claude/skills/_archived/ + commit +6. Update bảng §9.1 trong rules.md + .claude/skills/README.md + docs/CLAUDE.md count +7. Log vào docs/changelog/skill-audit-{YYYY-MM}.md (1 page max) +``` + +**Trigger:** Khi user nói "audit skill", "check skill list", "skill staleness", "định kỳ kiểm tra skill" → chạy workflow này. + +**Lịch chính thức:** +- Tháng 1, 2, 3, ... — đầu tháng audit (1 buổi sáng) +- Hoặc khi bắt đầu Phase mới (vd Phase 6) → audit ngay trước phase +- Hoặc khi `docs/gotchas.md` vượt mốc (cứ +5 gotcha thì xem có gom thành skill được không) + +### 9.5 Anti-patterns + +❌ **KHÔNG bulk-clone repo skill 3rd party** — phần lớn doc-dump generic, không có `when-to-use`, dễ trigger sai. + +❌ **KHÔNG viết skill chỉ để "có thêm"** — skill = trigger semantic match, nếu description quá chung sẽ trigger nhầm trong session khác. + +❌ **KHÔNG copy nội dung skill từ docs/ sang SKILL.md** — skill phải ngắn gọn, action-oriented; docs/ là reference dài. Skill dẫn chiếu docs. + +❌ **KHÔNG bỏ qua skill khi gặp task khớp** — tự suy luận lại = lãng phí context + dễ sai. + +## 10. Liên quan - [`CLAUDE.md`](../CLAUDE.md) — entry point cho AI agent - [`architecture.md`](architecture.md) — kiến trúc chi tiết (layered, CQRS, state machine) - [`gotchas.md`](gotchas.md) — pitfalls đã gặp - [`database/database-guide.md`](database/database-guide.md) — DB conventions - [`flows/`](flows/) — sequence diagram per feature +- [`../.claude/skills/README.md`](../.claude/skills/README.md) — skill index 6 skill