@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8
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/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/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/validation.js +2 -3
- package/package.json +18 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- 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/validation.js +3 -4
- 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
|
@@ -1,42 +1,45 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sequence-execution-plan
|
|
3
|
-
description:
|
|
3
|
+
description: Sắp thứ tự nhiều hạng mục công việc ALP theo phụ thuộc thật, theo kiểm chứng, và theo quyền ghi. Dùng khi main hay lead điều phối nhiều kết quả, hoặc khi phải lập lại kế hoạch sau một chỗ chặn, một tiền đề đã đổi, hay một lần bị từ chối.
|
|
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
|
-
|
|
41
|
-
|
|
42
|
-
|
|
6
|
+
# Sắp thứ tự công việc thực thi được
|
|
7
|
+
|
|
8
|
+
Dùng task contract và các bằng chứng có sẵn. Thẩm quyền lập kế hoạch đến từ việc được
|
|
9
|
+
giao hiện tại: main điều phối kết quả tổng thể; lead lập kế hoạch thực thi kỹ thuật
|
|
10
|
+
trong phạm vi được giao của mình. Peer báo các phụ thuộc chứ không tự sang tay quyền sở
|
|
11
|
+
hữu hay nới rộng kế hoạch.
|
|
12
|
+
|
|
13
|
+
Tách mức gấp ra khỏi thứ tự phụ thuộc. Một điều kiện tiên quyết có mức ưu tiên thấp hơn vẫn
|
|
14
|
+
có thể phải chạy trước, nhưng nó không đóng được kết quả có ưu tiên cao hơn. Một biện pháp
|
|
15
|
+
giảm nhẹ chỉ làm giảm tác động hiện tại; nó không phải bằng chứng của một bản sửa bền.
|
|
16
|
+
|
|
17
|
+
Hãy dựng các hạng mục nhỏ mà mỗi hạng mục đều mang lại tiến triển quan sát được. Giữ phần hiện
|
|
18
|
+
thực và phần kiểm chứng trực tiếp của nó cùng chỗ. Hãy tách ra khi một quyết định chưa ngã ngũ
|
|
19
|
+
chặn một phần, khi các kết quả riêng cần được nghiệm thu độc lập, hoặc khi một lần chờ tài
|
|
20
|
+
nguyên/chờ người sẽ làm nghẽn công việc không liên quan. Đừng áp một số lượng task cố định lên
|
|
21
|
+
một thay đổi đơn giản.
|
|
22
|
+
|
|
23
|
+
Với mỗi hạng mục, hãy xác định kết quả, người sở hữu, đường dẫn sở hữu/bị loại, các điều kiện
|
|
24
|
+
tiên quyết thật, đường ráp để kiểm chứng, bằng chứng hoàn thành, và trạng thái hiện tại. Phân
|
|
25
|
+
biệt phần nền bắt buộc với phần cải thiện tuỳ chọn và những abstraction phỏng đoán cho tương
|
|
26
|
+
lai.
|
|
27
|
+
|
|
28
|
+
Xếp thành Now, Next và Later kèm giải thích nhân quả: điều kiện tiên quyết nào chặn
|
|
29
|
+
kết quả nào, phép kiểm nào xác nhận nó, và quyết định nào mở ra nhánh kế tiếp.
|
|
30
|
+
Đọc [định dạng kế hoạch](references/plan-template.md) khi một kế hoạch nhiều hạng mục có tính bền
|
|
31
|
+
là hữu ích. Dùng chỗ đặt kế hoạch mà project đã có; đừng tạo các quy tắc ignore không liên quan
|
|
32
|
+
hay một cây phân cấp lập kế hoạch mới chỉ để thoả skill này.
|
|
33
|
+
|
|
34
|
+
Việc giao việc trên Paseo hiện tại là tuần tự: mỗi agent cha chờ kết quả của một agent con.
|
|
35
|
+
Đừng hứa hẹn có nhiều worker chạy song song hay có hộp thư ngược lên trong lúc chạy. Một
|
|
36
|
+
checkout dùng chung chỉ có một người ghi tại một thời điểm; main muốn can thiệp thì quyền sở
|
|
37
|
+
hữu phải được nhả ra trước. Hãy cấp phát port, đường dẫn scratch và các tài nguyên độc quyền
|
|
38
|
+
khác nếu việc được giao có dùng chúng. Chỉ riêng việc tách worktree không hề cô lập port hay
|
|
39
|
+
một cơ sở dữ liệu dùng chung.
|
|
40
|
+
|
|
41
|
+
Hãy lập lại kế hoạch khi bằng chứng làm đổi một tiền đề, khi một phụ thuộc chặn công việc, khi
|
|
42
|
+
người dùng đổi phạm vi, hoặc khi bị từ chối nhiều lần cho thấy việc được giao cần cấu trúc lại.
|
|
43
|
+
Cập nhật các dữ kiện và ràng buộc trước khi phát ra một brief đã sửa. Giữ lại các tiêu chí
|
|
44
|
+
nghiệm thu chưa xong khi gộp các hạng mục. Bản ứng viên vẫn chỉ là ứng viên cho tới khi
|
|
45
|
+
reviewer có trách nhiệm đã đánh giá chính bằng chứng thật.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Định dạng kế hoạch tương xứng
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Dùng các field liên quan; một kế hoạch là thứ giúp ra quyết định, không phải bài tập điền mẫu.
|
|
4
4
|
|
|
5
5
|
```text
|
|
6
6
|
Outcome and acceptance evidence:
|
|
@@ -17,6 +17,6 @@ Open decisions and blockers:
|
|
|
17
17
|
Replan reason, when applicable:
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
accepted
|
|
22
|
-
|
|
20
|
+
Trạng thái có thể là ready, blocked, running, candidate, accepted hay rejected. Một hạng mục
|
|
21
|
+
được accepted dựa trên artifact và kiểm chứng; riêng việc một process thoát thành công không
|
|
22
|
+
phải là một tiêu chí nghiệm thu. Bỏ các field branch/SHA ở những project không dùng Git.
|
|
@@ -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.
|