@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.
Files changed (124) hide show
  1. package/dist/library-edit.d.ts +51 -2
  2. package/dist/library-edit.js +160 -8
  3. package/dist/library.d.ts +14 -1
  4. package/dist/library.js +73 -5
  5. package/dist/models.d.ts +35 -0
  6. package/dist/models.js +17 -1
  7. package/dist/packs.d.ts +57 -0
  8. package/dist/packs.js +247 -0
  9. package/dist/permissions.d.ts +3 -2
  10. package/dist/permissions.js +6 -3
  11. package/dist/profiles.js +3 -3
  12. package/dist/providers.d.ts +2 -4
  13. package/dist/providers.js +20 -4
  14. package/dist/skill-validate.d.ts +85 -0
  15. package/dist/skill-validate.js +298 -0
  16. package/dist/upgrade.d.ts +10 -0
  17. package/dist/upgrade.js +112 -6
  18. package/dist/validation.js +2 -3
  19. package/package.json +18 -2
  20. package/src/library-edit.js +170 -8
  21. package/src/library.js +96 -6
  22. package/src/models.js +24 -0
  23. package/src/packs.js +246 -0
  24. package/src/permissions.d.ts +3 -2
  25. package/src/permissions.js +13 -3
  26. package/src/profiles.js +4 -4
  27. package/src/providers.js +20 -5
  28. package/src/resolver.js +1 -1
  29. package/src/skill-validate.js +287 -0
  30. package/src/upgrade.js +54 -6
  31. package/src/validation.js +3 -4
  32. package/templates/ALP.md +52 -52
  33. package/templates/agents/lead/AGENT.md +77 -74
  34. package/templates/agents/main/AGENT.md +153 -145
  35. package/templates/agents/oracle/AGENT.md +38 -37
  36. package/templates/agents/peer/AGENT.md +56 -52
  37. package/templates/agents/reviewer/AGENT.md +63 -65
  38. package/templates/agents/supervisor/AGENT.md +63 -63
  39. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  40. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  41. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  42. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  43. package/templates/packs/architecture/pack.json +7 -0
  44. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  45. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  46. package/templates/packs/backend/pack.json +6 -0
  47. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  48. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  49. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  50. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  51. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  52. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  53. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  54. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  55. package/templates/packs/design/pack.json +6 -0
  56. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  57. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  58. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  59. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  60. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  61. package/templates/packs/frontend/pack.json +6 -0
  62. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  63. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  64. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  65. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  66. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  67. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  68. package/templates/packs/integration/pack.json +6 -0
  69. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  70. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  71. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  72. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  73. package/templates/packs/operations/pack.json +6 -0
  74. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  75. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  76. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  77. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  78. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  79. package/templates/packs/quality/pack.json +6 -0
  80. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  81. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  82. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  83. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  84. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  85. package/templates/role-skills.json +4 -4
  86. package/templates/skills/architecture-docs/SKILL.md +81 -0
  87. package/templates/skills/architecture-docs/references/adr.md +62 -0
  88. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  89. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  90. package/templates/skills/bug-loop/SKILL.md +41 -40
  91. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  92. package/templates/skills/compact/SKILL.md +2 -2
  93. package/templates/skills/curate/SKILL.md +6 -5
  94. package/templates/skills/feature-architecture/SKILL.md +90 -0
  95. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  96. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  97. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  98. package/templates/skills/goal-griller/SKILL.md +27 -27
  99. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  100. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  101. package/templates/skills/release-readiness/SKILL.md +83 -0
  102. package/templates/skills/release-readiness/references/checklist.md +40 -0
  103. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  104. package/templates/skills/safe-refactor/SKILL.md +84 -0
  105. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  106. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  107. package/templates/skills/security-review/SKILL.md +87 -0
  108. package/templates/skills/security-review/references/checklist.md +74 -0
  109. package/templates/skills/security-review/references/severity.md +61 -0
  110. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  111. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  112. package/templates/skills/skill-authoring/SKILL.md +84 -0
  113. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  114. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  115. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  116. package/templates/skills/smart-commits/SKILL.md +37 -36
  117. package/templates/skills/test-strategy/SKILL.md +83 -0
  118. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  119. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  120. package/templates/skills/xia/SKILL.md +40 -38
  121. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  122. package/templates/teams/cafe/team.json +1 -1
  123. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  124. package/templates/teams/pho/team.json +1 -1
@@ -1,42 +1,45 @@
1
1
  ---
2
2
  name: sequence-execution-plan
3
- description: Order multiple ALP work items by real dependencies, verification, and writer ownership. Use when Main or Lead coordinates several outcomes or must replan after a blocker, changed premise, or rejection.
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
- # Order executable work
7
-
8
- Use the task contract and available evidence. Planning authority comes from the
9
- current assignment: main coordinates the overall outcome; lead plans technical
10
- execution within its assigned scope. A peer reports dependencies instead of
11
- reassigning ownership or widening the plan.
12
-
13
- Separate urgency from dependency order. A lower-priority prerequisite may need to
14
- run first, but it does not close the higher-priority outcome. A mitigation reduces
15
- current impact; it is not proof of a durable fix.
16
-
17
- Build small work items that each deliver observable progress. Keep implementation
18
- and its direct verification together. Split when an unresolved decision blocks one
19
- part, separate outcomes need independent acceptance, or a resource/human wait would
20
- stall unrelated work. Do not impose a fixed task count on a simple change.
21
-
22
- For each item identify the result, owner, owned/excluded paths, true prerequisites,
23
- verification seam, completion evidence, and current state. Distinguish necessary
24
- foundations from optional improvements and speculative future abstractions.
25
-
26
- Arrange Now, Next, and Later using causal explanations: which prerequisite blocks
27
- which outcome, which check validates it, and which decision opens the next branch.
28
- Read [the plan format](references/plan-template.md) when a durable multi-item plan
29
- helps. Use the project's existing plan location; do not create unrelated ignore
30
- rules or a new planning hierarchy just to satisfy this skill.
31
-
32
- Current Paseo delegation is sequential: each parent waits for one child's result.
33
- Do not promise parallel workers or live upstream mailboxes. A shared checkout has
34
- one writer at a time; main intervention requires ownership to be released first.
35
- Allocate ports, scratch paths, and other exclusive resources if the assignment uses
36
- them. Separate worktrees alone do not isolate ports or a shared database.
37
-
38
- Replan when evidence changes a premise, a dependency blocks work, the user changes
39
- scope, or repeated rejection reveals that the assignment needs restructuring.
40
- Update the facts and constraints before issuing a revised brief. Preserve unfinished
41
- acceptance criteria when merging items. Candidate remains candidate until the
42
- responsible reviewer has evaluated the actual evidence.
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
- # Proportional plan format
1
+ # Định dạng kế hoạch tương xứng
2
2
 
3
- Use the relevant fields; a plan is a decision aid, not a form-completion exercise.
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
- States can be ready, blocked, running, candidate, accepted, or rejected. An item is
21
- accepted based on artifacts and verification; a successful process exit is not an
22
- acceptance criterion by itself. Omit branch/SHA fields in non-Git projects.
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: Package existing owned changes into focused local Git commits with verification evidence. Use when commits are requested or part of the assigned handoff; do not activate merely because a file was edited.
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
- # Package the authorized changes
7
-
8
- Confirm this is a Git repository and that local commits belong to the requested
9
- deliverable. A non-Git task returns file artifacts; do not initialize Git merely to
10
- produce a SHA. A read-only task cannot commit. Existing user authorization remains
11
- valid; the skill adds no confirmation gate or permission to push.
12
-
13
- Inspect the root, branch, status, unresolved merges, staged paths, and staged/unstaged
14
- diffs with Git commands. Verify any supplied base revision. Preserve work outside
15
- the assignment. If unrelated staged changes would enter the commit, stop packaging
16
- and report the conflict without resetting or unstaging someone else's work.
17
-
18
- Group changes by behavior and intent. Keep implementation and its direct tests
19
- together where useful. Read each included diff and stage only the owned paths or
20
- hunks. Avoid whole-tree staging in a shared checkout. Do not add unrelated fixes or
21
- formatting to make a commit easier.
22
-
23
- Run the relevant checks from the project/brief, reusing recent results when still
24
- applicable. State failures and omissions accurately. If hooks may cause external
25
- side effects, inspect their configured behavior before invoking them and stay within
26
- the task's authorization. Do not bypass hooks or protections to get a green commit.
27
-
28
- Create focused messages explaining the change and its purpose, following the
29
- repository's convention. Check commit success before reading the candidate SHA.
30
- Verify that the candidate contains only the intended scope and that the base
31
- relationship is valid when a base was supplied. A failed commit produces no new
32
- candidate, and an already-clean tree needs no empty commit.
33
-
34
- Do not rewrite a candidate already handed off for review. Corrections should be
35
- new commits unless rewriting was specifically agreed. Push requires existing explicit
36
- authorization for the intended remote/branch; a configured remote does not provide it.
37
-
38
- Return root, branch, actual base/candidate SHAs, commit summary, owned scope, checks
39
- and results, remaining work, and push status. Lead/main still review the artifact;
40
- the writer does not self-accept its work.
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.