@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bridges.js +2 -2
- package/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packaged.d.ts +45 -12
- package/dist/packaged.js +46 -5
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +16 -10
- package/package.json +18 -2
- package/src/bridges.js +3 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packaged.js +77 -8
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/validation.d.ts +1 -0
- package/src/validation.js +21 -12
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: skill-authoring
|
|
3
|
+
description: "Thiết kế, viết, kiểm tra và cải thiện một agent skill: yêu cầu, description để kích hoạt, cách hé dần thông tin, các reference, script tuỳ chọn và cách đánh giá kích hoạt. Dùng khi tạo một skill mới hoặc khi sửa lại phạm vi, description hay cấu trúc của một skill. Không dùng để rà soát hay cho nghỉ toàn bộ danh mục bài học và skill; hãy dùng curate."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Viết một skill
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
- Một quy trình lặp lại, ba bài học liên quan trở lên, hay một yêu cầu của người dùng đòi một
|
|
10
|
+
skill mới.
|
|
11
|
+
- Một skill đang có kích hoạt sai chỗ, bỏ sót việc của nó, hay đã dài tới mức khó theo.
|
|
12
|
+
- Một skill cần thêm reference, một script tất định, hay một bản ghi đè riêng cho project.
|
|
13
|
+
|
|
14
|
+
## Không dùng cho
|
|
15
|
+
- Gộp, tỉa hay cho nghỉ các bài học và skill trên toàn danh mục: dùng curate.
|
|
16
|
+
- Hướng dẫn dùng một lần cho một task duy nhất: hãy đặt chúng vào brief hoặc ALP.md.
|
|
17
|
+
- Đổi thẩm quyền của role: một skill không cấp quyền nào và không thể nới rộng phạm vi.
|
|
18
|
+
|
|
19
|
+
## Điều kiện tiên quyết
|
|
20
|
+
- Đọc ALP.md và các skill đã gán cho các role đích; tránh trùng lặp.
|
|
21
|
+
- Biết nó sẽ sống ở đâu: thư viện của người dùng (do main đề xuất qua `alp_skill`) hay project
|
|
22
|
+
(`.alp/skills/<name>/` trong repository, một thay đổi thường được review).
|
|
23
|
+
- Có ít nhất một task thật mà skill này đáng lẽ đã giúp được.
|
|
24
|
+
|
|
25
|
+
## Quy trình
|
|
26
|
+
1. **Yêu cầu.** Viết công việc nó làm trong một câu, các role dùng nó, các input nó
|
|
27
|
+
giả định, và kết quả quan sát được mà nó phải trả về. Bỏ mọi thứ mà một agent có năng lực
|
|
28
|
+
vốn đã làm được mà không cần hướng dẫn.
|
|
29
|
+
2. **Đặc tả kích hoạt.** Liệt kê 3-5 task dương phải chọn nó và 3-5 task lân cận
|
|
30
|
+
phải không chọn nó, mỗi task nêu tên skill thực sự sở hữu nó.
|
|
31
|
+
3. **Description.** Đây là đoạn chữ duy nhất một agent thấy khi phiên bắt đầu. Nêu LÀM GÌ, rồi
|
|
32
|
+
"Dùng khi ...", rồi "Không dùng cho ... (dùng X)". Giữ các từ khoá trong 400
|
|
33
|
+
ký tự đầu mà index của ALP hiển thị; `alp_skill` chỉ nhận tối đa 300.
|
|
34
|
+
4. **Các mức hé dần.** Mức 0: tên và description (luôn được nạp). Mức 1:
|
|
35
|
+
thân SKILL.md, đọc khi description khớp. Mức 2: các reference, chỉ đọc tại
|
|
36
|
+
bước có link tới chúng. Mức 3: script và asset, chạy khi cần và không bao giờ lúc khám phá.
|
|
37
|
+
Đặt mỗi dữ kiện ở mức thấp nhất mà vẫn tới được bước cần nó.
|
|
38
|
+
5. **Thân bài.** Các mục theo thứ tự: Khi dùng, Không dùng cho, Điều kiện tiên quyết, Quy trình
|
|
39
|
+
(có số), Ràng buộc, Kiểm chứng, Xử lý khi thất bại, Tài liệu tham chiếu. Câu mệnh lệnh gọn,
|
|
40
|
+
không kể lịch sử, không nhắc lại quy tắc của role, nhiều nhất khoảng 110 dòng.
|
|
41
|
+
6. **Reference.** Một chủ đề một file, tên kebab-case, chỉ một mức sâu, mỗi file được link từ
|
|
42
|
+
bước cần nó kèm chữ "đọc khi ...". Tách một reference khi nó phủ hai
|
|
43
|
+
quyết định; xoá reference không bước nào link tới.
|
|
44
|
+
7. **Script (tuỳ chọn).** Chỉ thêm khi cùng một phép biến đổi hay phép kiểm tất định bị lặp lại
|
|
45
|
+
và dễ sai nếu diễn bằng lời. Dùng Node `.mjs` chạy bằng `node`; không tự động cài
|
|
46
|
+
dependency; in một thông điệp rõ ràng nêu tên dependency còn thiếu
|
|
47
|
+
rồi thoát với mã khác 0; kèm một test hoặc một lần chạy mẫu với output mong đợi.
|
|
48
|
+
8. **Kiểm tra.** Chạy `alp skill check <name|dir>`, rồi `--strict` trước khi đề xuất.
|
|
49
|
+
Sửa mọi error và warning; riêng frontmatter hợp lệ chẳng chứng minh gì về chất lượng.
|
|
50
|
+
9. **Đánh giá.** Chạy các tình huống kích hoạt đối chiếu với description và làm một lần chạy
|
|
51
|
+
khan trên một task thật bằng cách theo thân bài sát từng chữ; ghi lại chỗ hụt và sửa chúng.
|
|
52
|
+
10. **Giao.** Skill thư viện: main đề xuất nó bằng `alp_skill` (name, description,
|
|
53
|
+
body, roles) và người dùng duyệt. `alp_skill` chỉ ghi SKILL.md, nên các reference
|
|
54
|
+
và script do người dùng thêm, hoặc thêm qua `alp skill new` / `alp skill edit`.
|
|
55
|
+
Skill của project: ghi `.alp/skills/<name>/` trong các đường dẫn sở hữu rồi handoff.
|
|
56
|
+
|
|
57
|
+
## Ràng buộc
|
|
58
|
+
- Đừng bao giờ ghi đè một skill thư viện mà người dùng đã sửa. Hãy đọc nó, rồi đề xuất một bản
|
|
59
|
+
mới bằng `alp_skill` với `replace: true`; người dùng duyệt hoặc từ chối.
|
|
60
|
+
- Muốn đổi hành vi cho riêng một project, hãy thêm một bản ghi đè trong `.alp/skills/<name>/`
|
|
61
|
+
thay vì sửa bản trong thư viện.
|
|
62
|
+
- Không dùng tên tool riêng của một runtime, không có secret, không có hướng dẫn push, phát
|
|
63
|
+
hành, cài dependency hay ghi ra ngoài các đường dẫn sở hữu.
|
|
64
|
+
- Giữ tên ổn định khi các role đã tham chiếu tới nó; đổi tên là cho nghỉ cộng với một skill
|
|
65
|
+
mới.
|
|
66
|
+
|
|
67
|
+
## Kiểm chứng
|
|
68
|
+
- `alp skill check <name> --strict` pass mà không có warning.
|
|
69
|
+
- Mọi tình huống dương đều chọn skill này; mọi tình huống âm đều chọn đúng phương án
|
|
70
|
+
được nêu tên hoặc không chọn gì; các ca nhập nhằng được giải quyết trong description.
|
|
71
|
+
- Lần chạy khan đã tới được kết quả đã nêu mà không phải tự ứng biến các bước còn thiếu.
|
|
72
|
+
- Mọi reference và script đều được link từ một bước và đều tồn tại.
|
|
73
|
+
|
|
74
|
+
## Xử lý khi thất bại
|
|
75
|
+
- Bộ kiểm báo error: sửa file rồi chạy lại; đừng sửa bộ kiểm hay bỏ qua `--strict`.
|
|
76
|
+
- Chồng lấn với một skill đang có: thu hẹp một description, hoặc đề xuất gộp qua curate.
|
|
77
|
+
- Người dùng từ chối đề xuất: sửa theo góp ý rồi đề xuất lại; đừng ghi
|
|
78
|
+
file thư viện trực tiếp.
|
|
79
|
+
- Không có task thật để chạy khan: hãy giao như một bản nháp và nói rõ phần đánh giá còn treo.
|
|
80
|
+
|
|
81
|
+
## Tài liệu tham chiếu
|
|
82
|
+
- [references/skill-anatomy.md](references/skill-anatomy.md) — đọc khi viết frontmatter, chọn các mục hay bố trí file (bước 3-7).
|
|
83
|
+
- [references/trigger-design.md](references/trigger-design.md) — đọc khi soạn hay chữa description và các điều kiện không kích hoạt (bước 2-3).
|
|
84
|
+
- [references/evaluation.md](references/evaluation.md) — đọc khi dựng bảng tình huống và chạy lượt đánh giá khan (bước 9).
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Đánh giá skill
|
|
2
|
+
|
|
3
|
+
Đọc khi dựng các tình huống kích hoạt cho một skill và khi chạy lượt đánh giá khan của nó.
|
|
4
|
+
|
|
5
|
+
## Bảng tình huống
|
|
6
|
+
Viết 8-12 dòng trước khi tuyên bố skill hoạt động được. Trộn các ca dương, âm và nhập nhằng.
|
|
7
|
+
|
|
8
|
+
| # | Task (theo cách người yêu cầu sẽ nói) | Role | Skill mong đợi | Không được chọn | Loại |
|
|
9
|
+
|---|---|---|---|---|---|
|
|
10
|
+
| 1 | "Thêm test cho endpoint hoàn tiền mới" | lead | test-strategy | bug-loop | positive |
|
|
11
|
+
| 2 | "Test hoàn tiền fail từ hôm qua" | peer | bug-loop | test-strategy | negative |
|
|
12
|
+
| 3 | "Thêm endpoint hoàn tiền và test của nó" | lead | feature-architecture, rồi test-strategy | - | ambiguous |
|
|
13
|
+
|
|
14
|
+
- Chỉ dùng những skill thực sự được gán cho role ở dòng đó.
|
|
15
|
+
- Các dòng âm lấy từ những skill lân cận gần nhất được nêu trong mục "Không dùng cho".
|
|
16
|
+
- Các dòng nhập nhằng phải kết thúc bằng một cách giải quyết: một trình tự, một điều kiện phân
|
|
17
|
+
định thêm vào một description, hoặc một chỗ chồng lấn được chấp nhận và nêu rõ trong cả hai
|
|
18
|
+
skill.
|
|
19
|
+
|
|
20
|
+
## Kiểm điều kiện kích hoạt
|
|
21
|
+
1. Đưa cho một agent mới, hoặc cho chính bạn khi chưa đọc thân bài, chỉ các dòng index (tên
|
|
22
|
+
cộng description) của các skill thuộc role đó cùng với đoạn chữ của task.
|
|
23
|
+
2. Ghi lại nó chọn skill nào và những chữ nào đã quyết định điều đó.
|
|
24
|
+
3. Trượt ở một dòng dương, hay trúng ở một dòng không được chọn, đều là khuyết điểm của
|
|
25
|
+
description; hãy sửa rồi chạy lại cả bảng, không chỉ dòng bị fail.
|
|
26
|
+
|
|
27
|
+
## Lượt chạy khan
|
|
28
|
+
1. Chọn một task thật, nhỏ, từ project hoặc từ lịch sử của nó.
|
|
29
|
+
2. Theo thân bài sát từng chữ, theo đúng thứ tự, chỉ đọc reference khi một bước link tới nó.
|
|
30
|
+
3. Ghi lại mọi chỗ bạn phải đoán, phải bỏ qua, hay phải ứng biến: mỗi chỗ là một hướng dẫn còn
|
|
31
|
+
thiếu hoặc bị sai.
|
|
32
|
+
4. Ghi lại bất kỳ bước nào không tạo ra output quan sát được: hãy siết nó lại hoặc xoá nó.
|
|
33
|
+
5. Nếu skill có script, hãy chạy chúng trên input thật và trên một ca thiếu dependency.
|
|
34
|
+
|
|
35
|
+
## Bản ghi bằng chứng
|
|
36
|
+
Giữ cùng với đề xuất hoặc handoff:
|
|
37
|
+
- bảng tình huống kèm lựa chọn thực tế và pass hay fail cho từng dòng;
|
|
38
|
+
- task đã chạy khan, các bước phải sửa, và đã sửa gì;
|
|
39
|
+
- output của `alp skill check <name> --strict`;
|
|
40
|
+
- các khoảng trống đã biết mà chưa được đánh giá.
|
|
41
|
+
|
|
42
|
+
## Đừng tuyên bố
|
|
43
|
+
- Chất lượng chỉ vì bộ kiểm pass: nó kiểm định dạng, không kiểm mức hữu dụng.
|
|
44
|
+
- Độ phủ từ những tình huống bạn viết ra mà chưa chạy.
|
|
45
|
+
- Có cải thiện từ một lần sửa mà chưa chạy lại đúng các tình huống đã thúc đẩy lần sửa đó.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Cấu tạo một skill
|
|
2
|
+
|
|
3
|
+
Đọc khi viết frontmatter của một skill, khi xếp thứ tự thân bài, hoặc khi bố trí các file của
|
|
4
|
+
nó.
|
|
5
|
+
|
|
6
|
+
## Bố cục
|
|
7
|
+
```
|
|
8
|
+
<name>/
|
|
9
|
+
SKILL.md required; Level 1
|
|
10
|
+
references/<topic>.md optional; Level 2, read when a step links it
|
|
11
|
+
scripts/<tool>.mjs optional; Level 3, run on demand only
|
|
12
|
+
assets/<file> optional; Level 3, templates or fixtures copied by a step
|
|
13
|
+
```
|
|
14
|
+
Skill thư viện sống trong `skills/<name>/` của thư viện người dùng; skill của project sống
|
|
15
|
+
trong `.alp/skills/<name>/`, và nó thay thế skill thư viện cùng tên trong project đó.
|
|
16
|
+
|
|
17
|
+
## Frontmatter
|
|
18
|
+
|
|
19
|
+
Ví dụ dưới đây để tiếng ANH có chủ ý (t-d11c mục 3, người dùng quyết định 2026-11-06): nó minh họa
|
|
20
|
+
định dạng frontmatter, không phải câu chữ nên viết. `description` của skill thật viết bằng ngôn ngữ
|
|
21
|
+
của người dùng.
|
|
22
|
+
```
|
|
23
|
+
---
|
|
24
|
+
name: release-notes
|
|
25
|
+
description: "Draft release notes from merged changes ... Use when ... Not for ..."
|
|
26
|
+
---
|
|
27
|
+
```
|
|
28
|
+
- `name`: chữ thường `a-z`, `0-9` và dấu gạch nối đơn; không gạch nối ở đầu, ở cuối hay hai
|
|
29
|
+
gạch liền; nhiều nhất 64 ký tự; phải bằng tên thư mục.
|
|
30
|
+
- `description`: một dòng, theo định dạng thì nhiều nhất 1024 ký tự; index của ALP hiển thị 400
|
|
31
|
+
ký tự đầu, và `alp_skill` chỉ nhận tối đa 300. Không có ngắt dòng, không có dấu ngoặc nhọn.
|
|
32
|
+
- Các khoá tuỳ chọn mà định dạng cho phép: `license`, `compatibility` (nhu cầu môi trường, ví
|
|
33
|
+
dụ "Node 20+, git"), `metadata` (một map từ khoá chuỗi sang giá trị chuỗi, như version hay
|
|
34
|
+
tác giả), `allowed-tools` (danh sách mang tính tư vấn; trong ALP nó không cấp gì). Các
|
|
35
|
+
template ALP được ship chỉ dùng `name` và `description`; chỉ thêm khoá tuỳ chọn khi có một
|
|
36
|
+
bên tiêu thụ thật sự đọc chúng.
|
|
37
|
+
|
|
38
|
+
## Các mục trong thân bài
|
|
39
|
+
| Mục | Chứa gì |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `# Title` | Tên công việc ở dạng mệnh lệnh |
|
|
42
|
+
| Khi dùng | Các tình huống cụ thể, phản chiếu các điều kiện kích hoạt trong description |
|
|
43
|
+
| Không dùng cho | Các công việc lân cận và skill sở hữu từng cái |
|
|
44
|
+
| Điều kiện tiên quyết | Những gì phải đọc hay phải biết trước bước 1 |
|
|
45
|
+
| Quy trình | Các bước có số, mỗi bước có một output quan sát được |
|
|
46
|
+
| Ràng buộc | Các giới hạn agent không được vượt |
|
|
47
|
+
| Kiểm chứng | Các phép kiểm chứng minh kết quả, không phải chứng minh sự nỗ lực |
|
|
48
|
+
| Xử lý khi thất bại | Làm gì khi một bước không hoàn tất được |
|
|
49
|
+
| Tài liệu tham chiếu | Một dòng cho mỗi file: link, rồi "đọc khi ..." |
|
|
50
|
+
|
|
51
|
+
## Quy tắc viết
|
|
52
|
+
- Mệnh lệnh, cụ thể, kiểm được: "Chạy câu lệnh test của project", không phải "đảm bảo chất
|
|
53
|
+
lượng".
|
|
54
|
+
- Mỗi gạch đầu dòng một ý; chỉ dùng số ở chỗ thứ tự có ý nghĩa.
|
|
55
|
+
- Nêu các giá trị mặc định và ngưỡng một lần; reference mở rộng thân bài, không bao giờ lặp lại
|
|
56
|
+
nó.
|
|
57
|
+
- Ưu tiên công cụ và quy ước của chính project; đừng bao giờ bịa ra câu lệnh.
|
|
58
|
+
- Giữ SKILL.md và từng reference trong khoảng 110 dòng; tách theo quyết định, không theo kích
|
|
59
|
+
cỡ.
|
|
60
|
+
|
|
61
|
+
## Script
|
|
62
|
+
- Node `.mjs`, chạy bằng `node scripts/<tool>.mjs <args>`; ưu tiên thư viện chuẩn.
|
|
63
|
+
- Đừng bao giờ cài package. Nếu một dependency tuỳ chọn không có, hãy in
|
|
64
|
+
"missing dependency: <name>; install it or skip step N" rồi thoát với mã 2.
|
|
65
|
+
- Output tất định, không dùng mạng trừ khi bước đó nói vậy, không ghi ra ngoài
|
|
66
|
+
đường dẫn được truyền vào làm tham số.
|
|
67
|
+
- Ship kèm một test hoặc một lần gọi mẫu có ghi tài liệu, kèm output mong đợi.
|
|
68
|
+
|
|
69
|
+
## Đánh version
|
|
70
|
+
- Một skill thư viện mà người dùng đã sửa là của người dùng: hãy đề xuất một bản mới bằng
|
|
71
|
+
`alp_skill` với `replace: true`; đừng bao giờ sửa trực tiếp file đó.
|
|
72
|
+
- Ghi các thay đổi về hành vi trong phần tóm tắt của đề xuất, không ghi trong thân bài.
|
|
73
|
+
- Các lần phá vỡ tương thích (đổi tên một mục mà một hook hay một role dựa vào, bỏ các
|
|
74
|
+
reference) là những version mới mà người dùng phải duyệt.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Thiết kế điều kiện kích hoạt
|
|
2
|
+
|
|
3
|
+
Đọc khi soạn một description, khi chọn các điều kiện không kích hoạt, hoặc khi chữa một skill nổ vào sai task.
|
|
4
|
+
|
|
5
|
+
## Hình dạng
|
|
6
|
+
`<LÀM GÌ, động từ trước>. Dùng khi <các điều kiện kích hoạt cụ thể>. Không dùng cho <các skill lân cận> (dùng <skill>).`
|
|
7
|
+
- LÀM GÌ: output hay thay đổi nó tạo ra, bằng những chữ mà một yêu cầu công việc sẽ dùng.
|
|
8
|
+
- KHI NÀO: các tình huống và danh từ xuất hiện trong yêu cầu thật: "test đang fail", "endpoint
|
|
9
|
+
mới", "ADR", "nhánh phát hành".
|
|
10
|
+
- KHÔNG DÙNG CHO: hai hay ba skill lân cận gần nhất, mỗi cái chỉ sang chủ của nó.
|
|
11
|
+
- Dồn các từ đặc trưng lên đầu; index có thể cắt chữ sau 400 ký tự.
|
|
12
|
+
|
|
13
|
+
## Chọn điều kiện kích hoạt
|
|
14
|
+
- Thu các cách diễn đạt thật từ các task, bài học và handoff trước đây rồi hãy viết.
|
|
15
|
+
- Ưu tiên danh từ chỉ công việc và kết quả, hơn là tên phương pháp mà người yêu cầu sẽ không
|
|
16
|
+
nói.
|
|
17
|
+
- Một skill, một việc. Nếu danh sách KHI NÀO cần chữ "hoặc" để nối các việc không liên quan,
|
|
18
|
+
hãy tách nó ra.
|
|
19
|
+
|
|
20
|
+
## Điều kiện không kích hoạt
|
|
21
|
+
- Nêu tên mọi skill đã cài có công việc kế cận; agent sẽ so các description với nhau.
|
|
22
|
+
- Phát biểu ranh giới dưới dạng một quy tắc quyết định: "đã có một lỗi tồn tại" thì về
|
|
23
|
+
bug-loop; "thiết kế test cho hành vi mới" thì ở lại đây.
|
|
24
|
+
- Đừng liệt kê các việc không liên quan; nhiễu làm yếu ranh giới.
|
|
25
|
+
|
|
26
|
+
## Các chỗ chồng lấn nhập nhằng
|
|
27
|
+
| Chồng lấn | Giải quyết bằng cách |
|
|
28
|
+
|---|---|
|
|
29
|
+
| Hai skill đều hợp lý | Thêm điều kiện phân định vào cả hai description |
|
|
30
|
+
| Một task cần cả hai theo thứ tự | Nói "rồi dùng X" trong bước ở thân bài, không nói trong description |
|
|
31
|
+
| Skill của project che skill thư viện | Cùng tên thì thay thế nó; tên mới thì phải nêu rõ phạm vi hẹp hơn của nó |
|
|
32
|
+
|
|
33
|
+
## Ví dụ
|
|
34
|
+
Tệ: `"Giúp làm tài liệu."` Không có LÀM GÌ, không có KHI NÀO, khớp với mọi thứ.
|
|
35
|
+
|
|
36
|
+
Tệ: `"Dùng khi cần cho kiến trúc, test, tài liệu, review hay lập kế hoạch."` Năm việc,
|
|
37
|
+
không có ranh giới, không có output.
|
|
38
|
+
|
|
39
|
+
Tốt: `"Viết và cập nhật tài liệu kiến trúc và ADR từ bằng chứng trong repository. Dùng khi một
|
|
40
|
+
ranh giới, một contract hay cấu trúc module đổi, hoặc khi tài liệu còn thiếu. Không dùng cho
|
|
41
|
+
thiết kế ở mức feature (dùng feature-architecture)."`
|
|
42
|
+
|
|
43
|
+
Tốt: `"Soạn release note từ các thay đổi đã merge kể từ tag gần nhất. Dùng khi chuẩn bị một bản
|
|
44
|
+
phát hành hay một mục changelog. Không dùng để quyết định một bản phát hành có sẵn sàng hay
|
|
45
|
+
chưa (dùng release-readiness)."`
|
|
46
|
+
|
|
47
|
+
## Checklist chữa lỗi
|
|
48
|
+
- Nổ quá thường xuyên: thêm một mục "Không dùng cho" nêu skill lân cận đang bị giành việc; thu
|
|
49
|
+
hẹp danh từ.
|
|
50
|
+
- Không bao giờ nổ: thêm những chữ mà yêu cầu thật dùng; đưa chúng lên đầu.
|
|
51
|
+
- Nổ đúng lý do nhưng thân bài bị bỏ qua: description hứa một thứ mà thân bài không
|
|
52
|
+
giao được; hãy làm chúng khớp nhau.
|
|
@@ -1,40 +1,41 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: smart-commits
|
|
3
|
-
description:
|
|
3
|
+
description: Gói các thay đổi đã sở hữu thành những commit Git cục bộ gọn và tập trung, kèm bằng chứng kiểm chứng. Dùng khi commit được yêu cầu hoặc là một phần của handoff được giao; đừng kích hoạt chỉ vì vừa sửa một file.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
6
|
+
# Gói các thay đổi đã được cấp quyền
|
|
7
|
+
|
|
8
|
+
Xác nhận đây là một repository Git và rằng các commit cục bộ thuộc về sản phẩm được
|
|
9
|
+
yêu cầu giao. Một task không dùng Git thì trả về artifact dạng file; đừng khởi tạo Git chỉ để
|
|
10
|
+
sinh ra một SHA. Một task chỉ đọc không được commit. Thẩm quyền người dùng đã cấp vẫn còn
|
|
11
|
+
hiệu lực; skill này không thêm cổng xác nhận nào và cũng không cấp quyền push.
|
|
12
|
+
|
|
13
|
+
Hãy xem xét root, nhánh, status, các lần merge chưa giải quyết, các đường dẫn đã stage, và diff
|
|
14
|
+
đã stage/chưa stage bằng các câu lệnh Git. Kiểm chứng mọi base revision được cấp. Giữ nguyên
|
|
15
|
+
phần việc nằm ngoài việc được giao. Nếu có các thay đổi đã stage không liên quan sẽ lọt vào
|
|
16
|
+
commit, hãy dừng việc đóng gói và báo xung đột đó, đừng reset hay bỏ stage phần việc của người
|
|
17
|
+
khác.
|
|
18
|
+
|
|
19
|
+
Nhóm các thay đổi theo hành vi và theo ý định. Giữ phần hiện thực cùng với test trực tiếp của
|
|
20
|
+
nó ở chỗ điều đó hữu ích. Đọc từng diff được đưa vào và chỉ stage các đường dẫn hay hunk mình
|
|
21
|
+
sở hữu. Tránh stage toàn bộ cây trong một checkout dùng chung. Đừng thêm các bản sửa hay chỉnh
|
|
22
|
+
format không liên quan để commit cho dễ.
|
|
23
|
+
|
|
24
|
+
Chạy các phép kiểm liên quan theo project/brief, dùng lại các kết quả gần đây khi chúng còn áp
|
|
25
|
+
dụng được. Nêu các chỗ fail và các chỗ bỏ sót cho chính xác. Nếu hook có thể gây tác dụng phụ
|
|
26
|
+
ra bên ngoài, hãy xem hành vi đã cấu hình của chúng trước khi gọi, và ở trong phạm vi thẩm
|
|
27
|
+
quyền của task. Đừng lách hook hay các cơ chế bảo vệ để lấy một commit xanh.
|
|
28
|
+
|
|
29
|
+
Soạn các thông điệp gọn và tập trung, giải thích thay đổi và mục đích của nó, theo
|
|
30
|
+
quy ước của repository. Kiểm xem commit có thành công trước khi đọc SHA ứng viên.
|
|
31
|
+
Xác minh rằng bản ứng viên chỉ chứa đúng phạm vi dự kiến, và quan hệ với base là
|
|
32
|
+
hợp lệ khi có cấp một base. Một lần commit fail thì không sinh ra bản ứng viên mới nào,
|
|
33
|
+
và một cây vốn đã sạch thì không cần một commit rỗng.
|
|
34
|
+
|
|
35
|
+
Đừng viết lại một bản ứng viên đã được handoff để review. Các bản sửa nên là những
|
|
36
|
+
commit mới, trừ khi việc viết lại đã được thống nhất riêng. Push đòi phải có thẩm quyền rõ ràng
|
|
37
|
+
đã cấp sẵn cho đúng remote/nhánh dự kiến; một remote đã cấu hình không hề cấp thẩm quyền đó.
|
|
38
|
+
|
|
39
|
+
Trả về root, nhánh, các SHA base/candidate thật, tóm tắt commit, phạm vi sở hữu, các phép kiểm
|
|
40
|
+
và kết quả, phần việc còn lại, và trạng thái push. Lead/main vẫn review artifact;
|
|
41
|
+
người ghi không tự nghiệm thu công việc của chính mình.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: test-strategy
|
|
3
|
+
description: "Thiết kế test cho một feature hay một thay đổi theo hành vi và rủi ro: unit, integration, contract, end-to-end, regression, các đường lỗi và ca biên, dùng chính các framework project đang có. Dùng khi lập kế hoạch hay review test cho hành vi mới hoặc hành vi đã đổi. Không dùng để gỡ một lỗi đang có (dùng bug-loop) hay để dựng test riêng cho một công cụ (dùng web-testing nếu đã cài)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Test theo hành vi và rủi ro
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
- Một feature, endpoint, schema hay một thay đổi hành vi cần kế hoạch test trước hoặc trong lúc
|
|
10
|
+
làm.
|
|
11
|
+
- Một lead đang viết phần test của một brief cho peer.
|
|
12
|
+
- Một reviewer hỏi liệu các test của một thay đổi có chứng minh được điều nó tuyên bố.
|
|
13
|
+
- Một contract public (API, CLI, định dạng file, event) đổi và tính tương thích là quan trọng.
|
|
14
|
+
|
|
15
|
+
## Không dùng cho
|
|
16
|
+
- Một test hay một hành vi vốn đã fail: dùng bug-loop để tái lập và sửa nó.
|
|
17
|
+
- Dựng môi trường riêng cho framework hay tự động hoá trình duyệt: dùng web-testing nếu đã cài.
|
|
18
|
+
- Chạy theo một con số phần trăm coverage; skill này không đặt mục tiêu cố định nào.
|
|
19
|
+
|
|
20
|
+
## Điều kiện tiên quyết
|
|
21
|
+
- Đọc ALP.md và câu lệnh test, bố cục, framework, fixture và helper của project.
|
|
22
|
+
- Biết hành vi dự kiến từ yêu cầu của người dùng, từ spec hay từ contract, không phải từ
|
|
23
|
+
implementation đang được kiểm.
|
|
24
|
+
- Biết các đường dẫn sở hữu; peer chỉ thêm test ở bên trong chúng.
|
|
25
|
+
|
|
26
|
+
## Quy trình
|
|
27
|
+
1. **Liệt kê các hành vi.** Viết từng hành vi quan sát được của thay đổi thành một câu:
|
|
28
|
+
input hay event, kết quả mong đợi, và ai phụ thuộc vào nó.
|
|
29
|
+
2. **Liệt kê các rủi ro.** Với mỗi hành vi, cái gì có thể hỏng, khả năng bao nhiêu, và tốn kém
|
|
30
|
+
cỡ nào. Bao gồm các đường lỗi (input không hợp lệ, dependency không có, timeout, bị từ chối
|
|
31
|
+
quyền) và các ca biên trong checklist risk-matrix có áp dụng.
|
|
32
|
+
3. **Chọn phép test rẻ nhất mà chứng minh được.** Với mỗi rủi ro, hãy chọn mức thấp nhất mà sẽ
|
|
33
|
+
fail nếu rủi ro đó xảy ra: unit cho logic thuần, integration cho việc nối dây và lưu trữ
|
|
34
|
+
thật, contract cho các hình dạng mà người khác dựa vào, end-to-end chỉ cho một đường người
|
|
35
|
+
dùng tối quan trọng mà không mức thấp nào phủ. Một test tốt cho mỗi rủi ro; bỏ các test
|
|
36
|
+
không chứng minh thêm điều gì.
|
|
37
|
+
4. **Tái dùng.** Dùng framework, fixture, factory và helper đang có. Chỉ thêm một
|
|
38
|
+
helper mới khi có hai test trở lên cần nó; đừng bao giờ thêm một dependency test mà không có
|
|
39
|
+
lần duyệt được chuyển lên main.
|
|
40
|
+
5. **Viết kế hoạch.** Một bảng ngắn: hành vi, rủi ro, mức, chỗ đặt test, và nó
|
|
41
|
+
đã tồn tại hay chưa. Đặt nó vào brief, note của task hay handoff.
|
|
42
|
+
6. **Viết các test.** Đặt tên mỗi test theo hành vi của nó. Khẳng định các kết quả quan sát
|
|
43
|
+
được, không khẳng định các lời gọi nội bộ. Chỉ mock các biên bên ngoài, và giữ hành vi được
|
|
44
|
+
tuyên bố nằm trong phạm vi kiểm.
|
|
45
|
+
7. **Cho thấy chúng fail khi chưa có thay đổi.** Chạy các test mới trên code trước khi
|
|
46
|
+
thay đổi (stash hoặc comment phần thay đổi trong một bản sao riêng, hoặc viết test trước)
|
|
47
|
+
và ghi lại lần fail. Sau đó chạy chúng với thay đổi và ghi lại lần pass.
|
|
48
|
+
8. **Chạy bộ test xung quanh** bằng câu lệnh test của project và báo kết quả.
|
|
49
|
+
|
|
50
|
+
## Ràng buộc
|
|
51
|
+
- Giá trị mong đợi đến từ yêu cầu hoặc từ các ví dụ tự tính ra một cách độc lập, không bao giờ
|
|
52
|
+
đến từ việc chạy implementation.
|
|
53
|
+
- Đừng làm yếu, bỏ qua hay xoá một test đang có để một thay đổi pass; hãy báo nó.
|
|
54
|
+
- Test phải tất định: kiểm soát thời gian, phần ngẫu nhiên (seed cố định), thứ tự,
|
|
55
|
+
mạng và trạng thái dùng chung. Không dùng sleep để đồng bộ.
|
|
56
|
+
- Quy tắc về test chập chờn: đừng merge một test đã biết là chập chờn; nếu xuất hiện một cái,
|
|
57
|
+
hãy ghi lại tỉ lệ fail và các điều kiện, chỉ cách ly nó bằng cơ chế của project và có người
|
|
58
|
+
sở hữu, rồi chuyển việc chẩn đoán sang bug-loop.
|
|
59
|
+
- Một test regression nằm đúng tại đường ráp mà bug hay rủi ro thực sự trú ở đó.
|
|
60
|
+
|
|
61
|
+
## Kiểm chứng
|
|
62
|
+
- Mỗi rủi ro đã liệt kê đều ứng với một test hoặc với một dòng "accepted, not tested" rõ ràng
|
|
63
|
+
kèm lý do.
|
|
64
|
+
- Mỗi test mới đều đã được quan sát là fail khi chưa có thay đổi và pass khi có nó, hoặc
|
|
65
|
+
handoff nói rõ vì sao lần chạy đó không thực hiện được.
|
|
66
|
+
- Câu lệnh test của project pass cho khu vực bị ảnh hưởng; các câu lệnh và kết quả đều có
|
|
67
|
+
trong handoff.
|
|
68
|
+
- Không có test mới nào phụ thuộc vào thời gian thực, vào thứ tự test hay vào service bên
|
|
69
|
+
ngoài.
|
|
70
|
+
|
|
71
|
+
## Xử lý khi thất bại
|
|
72
|
+
- Không có đường ráp test dùng được: đề xuất thay đổi đường ráp nhỏ nhất cho lead hay main;
|
|
73
|
+
đừng tự ý cấu trúc lại code.
|
|
74
|
+
- Không chạy được lần trước khi thay đổi (không có lịch sử, code sinh ra): nêu rõ giới hạn và
|
|
75
|
+
dùng cách chèn lỗi trong một bản sao riêng nếu rủi ro biện minh được.
|
|
76
|
+
- Một test đang có fail trước cả thay đổi của bạn: hãy dừng, ghi lại, và chuyển nó sang
|
|
77
|
+
bug-loop.
|
|
78
|
+
- Yêu cầu chưa rõ với một ca biên: liệt kê nó thành một câu hỏi mở; đừng mã hoá một phỏng đoán
|
|
79
|
+
vào test.
|
|
80
|
+
|
|
81
|
+
## Tài liệu tham chiếu
|
|
82
|
+
- [references/risk-matrix.md](references/risk-matrix.md) — đọc khi liệt kê rủi ro và ca biên, và khi chọn mức test (bước 2-3).
|
|
83
|
+
- [references/contract-tests.md](references/contract-tests.md) — đọc khi thay đổi chạm tới một API, protocol, schema, định dạng file hay một contract khác hướng ra bên tiêu thụ.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Contract test
|
|
2
|
+
|
|
3
|
+
Đọc khi một thay đổi chạm tới một API, protocol, output CLI, event, schema hay định dạng file mà code khác hoặc người dùng khác dựa vào.
|
|
4
|
+
|
|
5
|
+
## Một contract test chứng minh điều gì
|
|
6
|
+
Rằng bên sản xuất vẫn phát ra, và bên tiêu thụ vẫn nhận, đúng hình dạng và ngữ nghĩa đã
|
|
7
|
+
thống nhất: tên field, kiểu, bắt buộc so với tuỳ chọn, mã trạng thái hay mã thoát, định dạng
|
|
8
|
+
lỗi, các bảo đảm về thứ tự và quy tắc đánh version. Nó không chứng minh logic nghiệp vụ.
|
|
9
|
+
|
|
10
|
+
## Chọn hình thức
|
|
11
|
+
| Tình huống | Hình thức |
|
|
12
|
+
|---|---|
|
|
13
|
+
| Đã có schema (OpenAPI, JSON Schema, proto, migration SQL) | Kiểm response hay bản ghi thật đối chiếu schema ngay trong test |
|
|
14
|
+
| Bên tiêu thụ và bên cung cấp nằm cùng một repository | Fixture dùng chung: test của bên cung cấp sinh ra nó, test của bên tiêu thụ đọc nó |
|
|
15
|
+
| Các team hay service tiêu thụ tách riêng | Contract do bên tiêu thụ dẫn dắt: bên tiêu thụ nêu kỳ vọng, bên cung cấp xác minh chúng trong build của mình |
|
|
16
|
+
| Output dạng chữ hay dạng file (CLI, báo cáo, file sinh ra) | Golden file so từng byte, kèm một đường cập nhật có review |
|
|
17
|
+
| Protocol trên đường truyền hay luồng event | Các message đã thu lại, replay vào bộ phân tích và được bên sản xuất phát ra |
|
|
18
|
+
|
|
19
|
+
Ưu tiên cơ chế project đã dùng; đừng thêm một framework contract test
|
|
20
|
+
mà không có lần duyệt được chuyển lên main.
|
|
21
|
+
|
|
22
|
+
## Golden file
|
|
23
|
+
- Lưu cạnh test, đặt tên theo ca đó; review chúng như review code.
|
|
24
|
+
- Chỉ chuẩn hoá những phần thật sự biến thiên (timestamp, id, đường dẫn tuyệt đối) bằng một
|
|
25
|
+
quy tắc tối giản và có ghi tài liệu.
|
|
26
|
+
- Cập nhật qua một câu lệnh hay một cờ rõ ràng, đừng bao giờ tự động cập nhật khi fail.
|
|
27
|
+
- Một diff của golden file trong một thay đổi phải được giải thích trong handoff.
|
|
28
|
+
|
|
29
|
+
## Kiểm tương thích ngược
|
|
30
|
+
- Các thay đổi dạng thêm vào (field tuỳ chọn mới, endpoint mới) phải để các fixture cũ vẫn
|
|
31
|
+
pass.
|
|
32
|
+
- Bỏ hay đổi tên một field, đổi một kiểu, siết chặt việc kiểm tra, đổi một
|
|
33
|
+
giá trị mặc định hay một mã lỗi đều là phá vỡ: hãy giữ một test với fixture cũ và xác nhận
|
|
34
|
+
kế hoạch khai tử dần hay việc nâng version với main.
|
|
35
|
+
- Bên đọc nên chịu được các field lạ nếu contract nói vậy; hãy test điều đó.
|
|
36
|
+
- Dữ liệu đã lưu: test rằng code mới đọc được dữ liệu do version trước ghi, và,
|
|
37
|
+
ở chỗ có hỗ trợ rollback, rằng code cũ đọc được dữ liệu do code mới ghi.
|
|
38
|
+
- API có version: giữ ít nhất một test cho mỗi version được hỗ trợ.
|
|
39
|
+
|
|
40
|
+
## Tập tối thiểu cho một thay đổi contract
|
|
41
|
+
1. Một fixture của hình dạng trước đây, vẫn được nhận (hoặc một lần phá vỡ đã ghi tài liệu và
|
|
42
|
+
đã duyệt).
|
|
43
|
+
2. Một fixture của hình dạng mới, do test của bên cung cấp sinh ra.
|
|
44
|
+
3. Test của bên tiêu thụ đọc hình dạng mới.
|
|
45
|
+
4. Một ca về hình dạng lỗi: request không hợp lệ hay message sai dạng sinh ra đúng lỗi đã ghi
|
|
46
|
+
tài liệu.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Bảng rủi ro và các ca biên
|
|
2
|
+
|
|
3
|
+
Đọc khi biến hành vi thành rủi ro, khi chọn mức test cho từng rủi ro, hoặc khi liệt kê các ca biên.
|
|
4
|
+
|
|
5
|
+
## Từ rủi ro sang mức test
|
|
6
|
+
| Rủi ro | Mức rẻ nhất mà chứng minh được | Ghi chú |
|
|
7
|
+
|---|---|---|
|
|
8
|
+
| Tính toán, phân tích cú pháp, rẽ nhánh sai | Unit | Các ca theo bảng trên nhiều input |
|
|
9
|
+
| Input không hợp lệ bị nhận hoặc input hợp lệ bị từ chối | Unit, cộng một integration tại biên | Kiểm tra ngay tại chỗ input đi vào |
|
|
10
|
+
| Nối dây: config, dependency injection, định tuyến | Integration | Đồ thị module thật, bên ngoài là fake |
|
|
11
|
+
| Lưu trữ: truy vấn, migration, transaction | Integration với store thật hoặc nhúng | Dùng chỗ dựng DB test đang có của project |
|
|
12
|
+
| Đổi hình dạng làm vỡ một bên tiêu thụ | Contract | Xem reference contract-tests |
|
|
13
|
+
| Một hành trình người dùng tối quan trọng vỡ từ đầu tới cuối | End-to-end, một đường | Chỉ khi các mức thấp hơn không thấy được |
|
|
14
|
+
| Một bug đã sửa trước đây quay lại | Regression tại đường ráp của bug gốc | Giữ lại bản tái lập gốc |
|
|
15
|
+
| Dependency chết, chậm hay báo lỗi | Integration với một fake biết chèn lỗi | Khẳng định timeout, retry, thông điệp lỗi |
|
|
16
|
+
| Lách quyền hay lách phân quyền | Integration xuyên qua chính phép kiểm thật | Test cả ca được phép và ca bị từ chối |
|
|
17
|
+
| Đồng thời: race, gửi hai lần, mất bản cập nhật | Integration với cách xen kẽ được kiểm soát | Lập lịch tất định, không dùng sleep |
|
|
18
|
+
| Regression hiệu năng trên một đường nóng đã biết | Benchmark hay phép kiểm ngân sách nếu project có | So các khối việc tương đương |
|
|
19
|
+
|
|
20
|
+
Ưu tiên theo khả năng xảy ra nhân với chi phí. Các rủi ro ít khả năng và ít tốn kém có thể được
|
|
21
|
+
chấp nhận mà không test; hãy nói rõ điều đó trong kế hoạch.
|
|
22
|
+
|
|
23
|
+
## Checklist ca biên theo loại input
|
|
24
|
+
**Chuỗi:** rỗng, chỉ có khoảng trắng, rất dài, Unicode (dấu kết hợp, emoji, RTL), khác nhau về
|
|
25
|
+
chữ hoa chữ thường, khoảng trắng ở đầu hay ở cuối, có ngắt dòng hay NUL bên trong, các ký tự
|
|
26
|
+
injection ứng với điểm tiêu đang dùng (SQL, shell, HTML, dấu phân cách đường dẫn).
|
|
27
|
+
|
|
28
|
+
**Số:** không, số âm, số một, giá trị lớn nhất và nhỏ nhất của kiểu, vừa vượt mỗi giới hạn,
|
|
29
|
+
số không nguyên ở chỗ mong đợi số nguyên, NaN và vô cực, làm tròn và độ chính xác
|
|
30
|
+
tiền tệ, số được mã hoá dưới dạng chuỗi.
|
|
31
|
+
|
|
32
|
+
**Tập hợp:** rỗng, một phần tử, có trùng, rất lớn, chưa sắp xếp, lồng nhau mà rỗng,
|
|
33
|
+
phần tử null, các biên phân trang (trang đầu, trang cuối, vượt quá cuối).
|
|
34
|
+
|
|
35
|
+
**Thời gian:** múi giờ và các lần chuyển DST, ngày nhuận, cuối tháng và cuối năm, lệch đồng hồ,
|
|
36
|
+
timestamp ở quá khứ hay tương lai xa, khoảng thời gian bằng không, hết hạn đúng tại biên.
|
|
37
|
+
Hãy đóng băng hoặc chèn đồng hồ vào.
|
|
38
|
+
|
|
39
|
+
**Đồng thời:** hai người ghi trên một bản ghi, retry sau khi thành công một phần, cùng một
|
|
40
|
+
message được giao trùng, hủy giữa lúc đang xử lý, các giả định về thứ tự.
|
|
41
|
+
|
|
42
|
+
**I/O và service bên ngoài:** thiếu file, bị từ chối quyền, đĩa đầy, đọc hay ghi
|
|
43
|
+
một phần, response sai dạng, timeout, response chậm, kết nối bị reset, hết lượt
|
|
44
|
+
retry, nội dung không phải UTF-8, symlink và path traversal.
|
|
45
|
+
|
|
46
|
+
**Quyền và danh tính:** ẩn danh, đã xác thực nhưng không có role, chủ sở hữu so với người dùng
|
|
47
|
+
khác, credential bị thu hồi hay hết hạn, các hành động chỉ dành cho admin bị gọi từ người dùng
|
|
48
|
+
thường.
|
|
49
|
+
|
|
50
|
+
**Trạng thái và vòng đời:** lần chạy đầu khi chưa có dữ liệu, nâng cấp từ dữ liệu của version
|
|
51
|
+
trước, gọi lặp lại (tính idempotent), các thao tác sau khi đã xoá hay đã đóng.
|
|
52
|
+
|
|
53
|
+
Hãy chọn những mục mà thay đổi thực sự với tới được; đừng mặc định test mọi dòng.
|