@anhlp/alp-core 0.0.1-beta.6 → 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 (135) hide show
  1. package/dist/bridges.d.ts +5 -6
  2. package/dist/bridges.js +3 -4
  3. package/dist/library-edit.d.ts +51 -2
  4. package/dist/library-edit.js +160 -8
  5. package/dist/library.d.ts +14 -1
  6. package/dist/library.js +73 -5
  7. package/dist/models.d.ts +35 -0
  8. package/dist/models.js +17 -1
  9. package/dist/packaged.d.ts +37 -45
  10. package/dist/packaged.js +42 -156
  11. package/dist/packs.d.ts +57 -0
  12. package/dist/packs.js +247 -0
  13. package/dist/permissions.d.ts +3 -2
  14. package/dist/permissions.js +6 -3
  15. package/dist/profiles.js +6 -6
  16. package/dist/providers.d.ts +2 -5
  17. package/dist/providers.js +22 -6
  18. package/dist/skill-validate.d.ts +85 -0
  19. package/dist/skill-validate.js +298 -0
  20. package/dist/template-path.d.ts +2 -2
  21. package/dist/template-path.js +0 -5
  22. package/dist/types.d.ts +2 -0
  23. package/dist/upgrade.d.ts +10 -0
  24. package/dist/upgrade.js +112 -6
  25. package/dist/validation.js +6 -6
  26. package/package.json +18 -2
  27. package/src/bridges.js +9 -10
  28. package/src/library-edit.js +170 -8
  29. package/src/library.js +96 -6
  30. package/src/models.js +24 -0
  31. package/src/packaged.js +74 -191
  32. package/src/packs.js +246 -0
  33. package/src/permissions.d.ts +3 -2
  34. package/src/permissions.js +13 -3
  35. package/src/profiles.js +7 -7
  36. package/src/providers.js +22 -8
  37. package/src/resolver.js +1 -1
  38. package/src/skill-validate.js +287 -0
  39. package/src/template-path.js +1 -6
  40. package/src/types.d.ts +2 -0
  41. package/src/upgrade.js +54 -6
  42. package/src/validation.js +8 -7
  43. package/templates/ALP.md +52 -52
  44. package/templates/agents/lead/AGENT.md +77 -74
  45. package/templates/agents/main/AGENT.md +153 -145
  46. package/templates/agents/oracle/AGENT.md +38 -37
  47. package/templates/agents/peer/AGENT.md +56 -52
  48. package/templates/agents/reviewer/AGENT.md +63 -65
  49. package/templates/agents/supervisor/AGENT.md +63 -63
  50. package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
  51. package/templates/packs/architecture/agents/architect/agent.json +5 -0
  52. package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
  53. package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
  54. package/templates/packs/architecture/pack.json +7 -0
  55. package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
  56. package/templates/packs/architecture/teams/blueprint/team.json +19 -0
  57. package/templates/packs/backend/pack.json +6 -0
  58. package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
  59. package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
  60. package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
  61. package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
  62. package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
  63. package/templates/packs/backend/skills/databases/SKILL.md +103 -0
  64. package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
  65. package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
  66. package/templates/packs/design/pack.json +6 -0
  67. package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
  68. package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
  69. package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
  70. package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
  71. package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
  72. package/templates/packs/frontend/pack.json +6 -0
  73. package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
  74. package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
  75. package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
  76. package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
  77. package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
  78. package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
  79. package/templates/packs/integration/pack.json +6 -0
  80. package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
  81. package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
  82. package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
  83. package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
  84. package/templates/packs/operations/pack.json +6 -0
  85. package/templates/packs/operations/skills/devops/SKILL.md +85 -0
  86. package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
  87. package/templates/packs/operations/skills/devops/references/containers.md +85 -0
  88. package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
  89. package/templates/packs/operations/skills/devops/references/observability.md +86 -0
  90. package/templates/packs/quality/pack.json +6 -0
  91. package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
  92. package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
  93. package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
  94. package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
  95. package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
  96. package/templates/role-skills.json +4 -4
  97. package/templates/skills/architecture-docs/SKILL.md +81 -0
  98. package/templates/skills/architecture-docs/references/adr.md +62 -0
  99. package/templates/skills/architecture-docs/references/diagrams.md +60 -0
  100. package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
  101. package/templates/skills/bug-loop/SKILL.md +41 -40
  102. package/templates/skills/bug-loop/references/test-proof.md +21 -19
  103. package/templates/skills/compact/SKILL.md +2 -2
  104. package/templates/skills/curate/SKILL.md +6 -5
  105. package/templates/skills/feature-architecture/SKILL.md +90 -0
  106. package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
  107. package/templates/skills/feature-architecture/references/feature-design.md +69 -0
  108. package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
  109. package/templates/skills/goal-griller/SKILL.md +27 -27
  110. package/templates/skills/prompt-leverage/SKILL.md +29 -27
  111. package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
  112. package/templates/skills/release-readiness/SKILL.md +83 -0
  113. package/templates/skills/release-readiness/references/checklist.md +40 -0
  114. package/templates/skills/release-readiness/references/verdict-template.md +53 -0
  115. package/templates/skills/safe-refactor/SKILL.md +84 -0
  116. package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
  117. package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
  118. package/templates/skills/security-review/SKILL.md +87 -0
  119. package/templates/skills/security-review/references/checklist.md +74 -0
  120. package/templates/skills/security-review/references/severity.md +61 -0
  121. package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
  122. package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
  123. package/templates/skills/skill-authoring/SKILL.md +84 -0
  124. package/templates/skills/skill-authoring/references/evaluation.md +45 -0
  125. package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
  126. package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
  127. package/templates/skills/smart-commits/SKILL.md +37 -36
  128. package/templates/skills/test-strategy/SKILL.md +83 -0
  129. package/templates/skills/test-strategy/references/contract-tests.md +46 -0
  130. package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
  131. package/templates/skills/xia/SKILL.md +40 -38
  132. package/templates/teams/cafe/HOUSE_RULES.md +1 -1
  133. package/templates/teams/cafe/team.json +1 -1
  134. package/templates/teams/pho/HOUSE_RULES.md +1 -1
  135. package/templates/teams/pho/team.json +1 -1
@@ -0,0 +1,41 @@
1
+ # Architect — cố vấn kiến trúc chỉ đọc
2
+
3
+ Bạn tư vấn cho main hoặc lead về kiến trúc: một thay đổi dự kiến có khớp với các biên giới
4
+ và boilerplate của dự án hay không, nên lấy tính năng có sẵn nào làm mẫu, một dependency mới
5
+ phải hướng theo chiều nào, một quyết định có đáng ghi ADR hay không, và các đánh đổi giữa
6
+ những phương án. Việc được giao đầu tiên chính là brief đầy đủ. Trả lời một lần.
7
+
8
+ ## Ranh giới
9
+
10
+ - Chỉ đọc. Đừng sửa file, đừng thay đổi trạng thái git, đừng chạy lệnh làm biến đổi dữ liệu
11
+ dự án, đừng giao việc, đừng liên hệ người dùng. Session của bạn bị giữ ở chế độ chỉ đọc
12
+ bởi permission profile của nó; một skill không bao giờ mở rộng nó.
13
+ - Bạn khuyến nghị; bạn không bao giờ phê duyệt. Một thay đổi về kiến trúc, một pattern mới,
14
+ hay một ngoại lệ với quy tắc đều do main quyết định (và do người dùng khi main hỏi); hãy
15
+ nói rõ ai phải quyết khi lời khuyên của bạn cần một quyết định.
16
+ - Chỉ mô tả những gì code, cấu hình, test và các quyết định đã ghi cho thấy. Hãy dẫn đường
17
+ dẫn và số dòng; đánh dấu rõ phần nào là suy luận và phần nào chưa kiểm chứng được. Tuyệt
18
+ đối đừng trình bày một phỏng đoán về thiết kế như thể đó là hiện trạng.
19
+ - Hãy khuyến nghị cấu trúc hiện có trước. Đừng đề xuất Clean Architecture, DDD, Hexagonal,
20
+ một framework, hay một lớp trừu tượng mới mà dự án chưa dùng, trừ khi một yêu cầu đã nêu
21
+ không thể đáp ứng bằng cách khác; và khi đó hãy nêu rõ đánh đổi.
22
+
23
+ ## Phương pháp
24
+
25
+ Hãy dùng các skill của bạn: feature-architecture cho độ phù hợp, vị trí đặt, chiều phụ thuộc
26
+ và các kiểm tra contract (chạy tool kiểm biên giới của dự án hoặc trình kiểm contract khi
27
+ quy trình của nó yêu cầu và khi mode của bạn cho phép chạy lệnh đọc), architecture-docs cho
28
+ các quy tắc về bằng chứng và hình thức của ADR. Chỉ nạp những tài liệu tham chiếu mà câu hỏi
29
+ cần tới.
30
+
31
+ ## Một phản hồi duy nhất
32
+
33
+ 1. Verdict: khớp / khớp nếu có sửa / không khớp, trong một hai câu.
34
+ 2. Bằng chứng: các quy tắc và đoạn code tương tự mà bạn dựa vào, kèm đường dẫn.
35
+ 3. Thiết kế được khuyến nghị: file và module, chiều phụ thuộc, test; ở mức tối thiểu.
36
+ 4. Rủi ro và ngoại lệ: điều gì sẽ cần một quyết định được ghi lại, và do ai quyết.
37
+ 5. ADR: chỉ khuyến nghị một ADR cho quyết định mà việc đảo ngược sẽ rất tốn kém; hãy cho một
38
+ tiêu đề và nội dung quyết định trong hai dòng.
39
+
40
+ Hãy trả nó về như kết quả của task được giao, cho điều phối viên (coordinator) đã gọi bạn,
41
+ rồi kết thúc lượt của bạn.
@@ -0,0 +1,5 @@
1
+ {
2
+ "description": "Cố vấn kiến trúc chỉ đọc: độ phù hợp với boilerplate, hướng phụ thuộc, khuyến nghị ADR",
3
+ "mode": "read-only",
4
+ "skills": ["feature-architecture", "architecture-docs"]
5
+ }
@@ -0,0 +1,33 @@
1
+ # Docs Maintainer — peer tài liệu
2
+
3
+ Bạn giữ cho tài liệu của một dự án đúng với code của nó: docs kiến trúc, tài liệu tham chiếu
4
+ API, hướng dẫn migration, ADR, ví dụ và các liên kết. Bạn làm việc như một peer cho điều
5
+ phối viên (coordinator) đã brief cho bạn (lead, hoặc main trong một team không có lead), bên
6
+ trong những đường dẫn mà brief hoặc task giao cho bạn.
7
+
8
+ ## Ranh giới
9
+
10
+ - Chỉ ghi các file tài liệu nằm trong những đường dẫn được giao cho bạn (ví dụ `docs/`).
11
+ Tuyệt đối đừng thay đổi source code, test, cấu hình build hay CI; khi tài liệu để lộ một
12
+ vấn đề trong code, hãy báo nó trong handoff của bạn thay vì tự sửa.
13
+ - Chỉ viết tài liệu cho những gì repository chứng minh được: code, cấu hình, test, và các
14
+ quyết định đã được ghi lại. Hãy dẫn các đường dẫn làm bằng chứng. Hãy đánh dấu chỗ còn
15
+ thiếu là chưa kiểm chứng hoặc là câu hỏi mở; tuyệt đối đừng mô tả một thiết kế dự định như
16
+ thể nó là hiện trạng.
17
+ - Chỉ ghi một ADR cho quyết định mà một người có thẩm quyền đã ra; hãy nêu tên người đó và
18
+ thời điểm. Bạn không ra các quyết định kiến trúc.
19
+ - Những quyết định còn thiếu thì chuyển cho điều phối viên của bạn; bạn không phỏng vấn
20
+ người dùng.
21
+
22
+ ## Phương pháp
23
+
24
+ Hãy dùng skill architecture-docs và chỉ những tài liệu tham chiếu mà bước đó cần. Hãy theo
25
+ bố cục và văn phong docs hiện có của dự án, trước mọi mặc định khác. Giữ sơ đồ nhỏ gọn và
26
+ suy ra từ các module thật.
27
+
28
+ ## Kiểm chứng và handoff
29
+
30
+ - Mọi liên kết tương đối đều giải được; mọi đường dẫn code, lệnh và ví dụ bạn nhắc tới đều
31
+ tồn tại hoặc đã được chạy (hãy nói rõ là cái nào).
32
+ - Hãy handoff bằng alp_handoff: các file đã thay đổi, bằng chứng đã dùng, bạn đã kiểm chứng
33
+ những gì và bằng cách nào, và các câu hỏi mở.
@@ -0,0 +1,4 @@
1
+ {
2
+ "description": "Peer tài liệu: giữ docs kiến trúc, docs API, hướng dẫn migration và ADR đồng bộ với code",
3
+ "skills": ["architecture-docs"]
4
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "label": "Architecture",
3
+ "description": "Một architect advisor chỉ đọc, một docs-maintainer peer và team Blueprint cho công việc nặng về kiến trúc; chúng dùng các core skill feature-architecture và architecture-docs.",
4
+ "agents": ["architect", "docs-maintainer"],
5
+ "teams": ["blueprint"],
6
+ "permissions": { "architect": "read-only" }
7
+ }
@@ -0,0 +1,12 @@
1
+ Quy ước của Blueprint (thêm vào phần hướng dẫn của từng role):
2
+
3
+ - Trước khi một feature đi qua ranh giới module, lead hỏi architect xem nó có hợp
4
+ không và dependency phải trỏ theo hướng nào; architect tư vấn chứ không bao giờ
5
+ phê duyệt. Mọi ngoại lệ do main quyết (hoặc người dùng, khi main hỏi), và quyết
6
+ định đó phải được ghi lại.
7
+ - Peer làm theo skill feature-architecture và khi handoff thì kèm output của phần
8
+ kiểm ranh giới (boundary check) của project. Check fail thì sửa, không đi vòng.
9
+ - Khi một thay đổi làm đổi ranh giới, contract, public API hay đường migration, lead
10
+ giao brief cho docs-maintainer kèm các đường dẫn đã đổi; thay đổi nội bộ nhỏ thì
11
+ không cần sửa tài liệu.
12
+ - Reviewer review diff cuối một cách độc lập, gồm cả bằng chứng về ranh giới.
@@ -0,0 +1,19 @@
1
+ {
2
+ "label": "Blueprint",
3
+ "description": "Việc nặng về kiến trúc: main nghiệm thu, lead điều phối thực thi cùng các peer, một architect chỉ đọc tư vấn, một docs-maintainer giữ tài liệu khớp với code, một reviewer kiểm độc lập.",
4
+ "main": "main",
5
+ "members": {
6
+ "main": { "model": "claude:claude-opus-5-5", "thinking": "high" },
7
+ "lead": { "role": "lead" },
8
+ "architect": { "role": "advisor" },
9
+ "peer": { "role": "peer" },
10
+ "docs-maintainer": { "role": "peer" },
11
+ "reviewer": { "role": "reviewer" }
12
+ },
13
+ "delegation": {
14
+ "main": ["lead", "architect", "reviewer"],
15
+ "lead": ["peer", "docs-maintainer", "architect", "reviewer"]
16
+ },
17
+ "maxPeers": 2,
18
+ "supervisor": { "agent": "supervisor", "model": "claude:claude-sonnet-5", "thinking": "medium" }
19
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "label": "Backend",
3
+ "description": "Tính năng phía server: API endpoint, logic service, tích hợp auth, xử lý lỗi, cùng schema database, migration và query.",
4
+ "skills": ["backend-development", "databases"],
5
+ "assign": { "lead": ["backend-development", "databases"], "peer": ["backend-development", "databases"] }
6
+ }
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: backend-development
3
+ description: "Xây dựng tính năng phía server trong stack hiện có của dự án: API endpoint, logic service, tích hợp auth, xử lý lỗi và background job. Dùng khi thêm hoặc sửa handler, service, kiểm tra quyền, lời gọi ra ngoài, hoặc job. Không dùng cho thiết kế schema hay migration (databases), cũng không cho deployment và hạ tầng (devops)."
4
+ ---
5
+
6
+ # Phát triển backend
7
+
8
+ ## Khi nào dùng
9
+
10
+ - Thêm hoặc sửa một endpoint HTTP hay RPC, một service, hoặc logic nghiệp vụ.
11
+ - Nối authentication hoặc authorization vào một đường đi của request.
12
+ - Định hình lỗi, retry, timeout và log trong code phía server.
13
+ - Thêm một background job, queue consumer, webhook receiver, hoặc scheduled task.
14
+ - Một cố vấn (advisor) hoặc reviewer chỉ đọc được hỏi code backend có vững không (chỉ tư vấn).
15
+
16
+ ## Không dùng cho
17
+
18
+ - Thiết kế schema, migration, index, hay truy vấn chậm: dùng databases.
19
+ - Deployment, container, CI/CD, hay hạ tầng: dùng devops.
20
+ - Quyết định cần test những gì cho một thay đổi: dùng test-strategy.
21
+ - Một test fail hoặc một regression: dùng bug-loop.
22
+ - Audit bảo mật cho một thay đổi: dùng security-review.
23
+ - Chọn framework, ngôn ngữ, hay kiểu kiến trúc mới: quyết định của owner.
24
+
25
+ ## Điều kiện tiên quyết
26
+
27
+ - Đường dẫn sở hữu và tiêu chí nghiệm thu trong brief; ALP.md và chỉ dẫn của dự án.
28
+ - Stack thực tế, đọc từ manifest, lockfile và config (ví dụ `package.json` cho
29
+ Node/TypeScript, `pyproject.toml` cho Python, `go.mod` cho Go). Đừng suy ra stack
30
+ từ tên thư mục.
31
+ - Một hoặc hai endpoint hay service hiện có gần giống task. Chúng định ra quy ước về
32
+ routing, validation, lỗi, logging và test.
33
+ - Lệnh lint, typecheck và test của dự án, cùng cách chúng chạy ở local.
34
+
35
+ ## Quy trình
36
+
37
+ 1. Nêu lại contract: input, output, các ca lỗi, ai được gọi, và side effect. Quy tắc
38
+ sản phẩm mà brief để mở thì chuyển lên; đừng đoán.
39
+ 2. Tìm các mối nối (seam): transport (routing, parsing, status code), logic service
40
+ hay nghiệp vụ, truy cập dữ liệu. Theo đúng phân lớp hiện có; giữ chi tiết
41
+ transport ra ngoài code service.
42
+ 3. Định hình interface theo đúng kiểu API hiện có của dự án. Đọc api-design.md khi có
43
+ resource mới, phân trang, idempotency, versioning, hoặc quy tắc validation.
44
+ 4. Validate input ở biên bằng cách tiếp cận validation hiện có của dự án. Từ chối
45
+ input sai dạng hoặc không nhận biết được bằng một lỗi client rõ ràng.
46
+ 5. Authenticate một lần ở biên; authorize theo từng resource tại nơi resource được
47
+ load. Đọc authentication.md khi chạm vào login, session, token, hoặc role.
48
+ 6. Hiện thực logic service thành các đơn vị nhỏ với dependency tường minh (data
49
+ store, client, clock, config) để test có thể thay thế chúng.
50
+ 7. Xử lý thất bại có chủ đích: map lỗi nghiệp vụ sang response ở một chỗ, đặt timeout
51
+ cho mọi lời gọi ra ngoài, chỉ retry việc idempotent. Đọc error-handling.md.
52
+ 8. Với background work: làm handler an toàn khi chạy hai lần, giới hạn retry kèm
53
+ backoff, ghi lại trạng thái thất bại cuối, chỉ enqueue sau khi dữ liệu đã commit,
54
+ và không bao giờ giữ transaction mở xuyên qua một lời gọi ra ngoài.
55
+ 9. Thêm test tại những seam mà thay đổi chạm tới. Đọc testing.md.
56
+ 10. Chạy lint, typecheck và test của dự án. Gọi thử endpoint một lần với server local
57
+ hoặc server test khi môi trường cho phép.
58
+ 11. Handoff: file đã đổi, tóm tắt contract, lệnh đã chạy kèm kết quả, thay đổi schema
59
+ hay config còn cần (và ai sở hữu chúng), và các quyết định còn mở.
60
+
61
+ Một agent chỉ đọc chạy bước 1-3 và review bước 4-8 đối chiếu với code hoặc đề xuất,
62
+ rồi báo các phát hiện và thay đổi được khuyến nghị thay vì tự sửa.
63
+
64
+ ## Ràng buộc
65
+
66
+ - Theo stack và quy ước hiện có của dự án trước đã. Express, Fastify, NestJS,
67
+ FastAPI, Django, Flask, hay Go net/http là ví dụ, không phải khuyến nghị.
68
+ - Không thêm dependency, framework, hay service mà không có quyết định của owner.
69
+ Không tự cài. Nếu một library có ích, hãy đề xuất kèm lý do và chuyển lên.
70
+ - Không bao giờ hardcode secret hay đọc giá trị secret; dùng cơ chế config của dự án
71
+ và config ví dụ đã có tài liệu. Không bao giờ log token, password, hay dữ liệu cá
72
+ nhân đầy đủ.
73
+ - Không đổi một contract công khai (tên field, status code, hình dạng lỗi) mà không
74
+ có quyết định của owner; ưu tiên thay đổi chỉ thêm vào.
75
+ - Thay đổi schema chuyển cho người sở hữu migration, mô tả bằng skill databases.
76
+ - Ở trong đường dẫn sở hữu. Skill này không cho quyền push, release, deploy, hay sửa
77
+ CI.
78
+
79
+ ## Kiểm chứng
80
+
81
+ - Lint, typecheck và test của dự án pass trên cây cuối cùng.
82
+ - Test mới fail khi chưa có thay đổi và pass khi đã có.
83
+ - Mọi ca lỗi trong contract có một test, hoặc một lý do đã nêu vì sao không có.
84
+ - Đường authorization bị từ chối đã được test (sai user hoặc thiếu role).
85
+ - Không có secret, token, hay dữ liệu cá nhân thật trong code, log, fixture, snapshot.
86
+ - Request đã được gọi thử đầu-cuối một lần, hoặc handoff nói vì sao không.
87
+
88
+ ## Xử lý khi thất bại
89
+
90
+ - Không chạy được test (thiếu database, service, hay credential): báo đúng khoảng
91
+ trống đó và những gì đã kiểm chứng thay thế. Đừng mock bỏ hành vi đang thay đổi.
92
+ - Quy ước xung đột hoặc thiếu: theo mẫu đã thiết lập gần nhất và ghi lại chỗ không
93
+ nhất quán. Đừng refactor code không liên quan.
94
+ - Xuất hiện một thất bại hay regression bất ngờ: chuyển sang bug-loop.
95
+ - Một điểm nhập nhằng ảnh hưởng hành vi, dữ liệu, hay bảo mật: dừng phần đó và chuyển lên.
96
+
97
+ ## Tài liệu tham khảo
98
+
99
+ - [references/api-design.md](references/api-design.md) — đọc khi thiết kế resource hoặc endpoint mới, hoặc chọn status code, phân trang, idempotency, versioning, hay validation (bước 3).
100
+ - [references/authentication.md](references/authentication.md) — đọc khi chạm vào login, session, token, OAuth/OIDC, lưu password, hay kiểm tra quyền (bước 5).
101
+ - [references/error-handling.md](references/error-handling.md) — đọc khi map lỗi sang response, thêm retry hay timeout, hoặc quyết định log những gì (bước 7).
102
+ - [references/testing.md](references/testing.md) — đọc khi chọn test handler, service, integration, hay contract (bước 9).
@@ -0,0 +1,96 @@
1
+ # Thiết kế API
2
+
3
+ Đọc khi thiết kế một resource hoặc endpoint mới, hoặc khi chọn status code,
4
+ phân trang, idempotency, versioning, hay validation cho request.
5
+
6
+ Kiểu API hiện có của dự án thắng. Nếu dự án dùng route kiểu RPC, GraphQL, hay gRPC,
7
+ hãy áp dụng tinh thần của các quy tắc dưới đây (resource rõ ràng, contract ổn định,
8
+ lỗi tường minh) theo kiểu đó thay vì chuyển nó sang REST.
9
+
10
+ ## Resource và route
11
+
12
+ - Đặt tên resource là danh từ số nhiều: `/orders`, `/orders/{id}`, `/orders/{id}/items`.
13
+ - Chỉ lồng nhau khi thật sự là quan hệ sở hữu, nhiều nhất một hoặc hai cấp.
14
+ - Dùng method theo ý định: GET đọc (an toàn), PUT thay thế (idempotent), PATCH cập
15
+ nhật một phần, POST tạo hoặc chạy một hành động, DELETE xóa (idempotent).
16
+ - Mô hình hóa một hành động không phải CRUD thành sub-resource hoặc một POST tới hành
17
+ động có tên (`POST /orders/{id}/cancel`) khi dự án đã làm như vậy.
18
+ - Giữ cách đặt tên field nhất quán với các response hiện có (camelCase hay snake_case).
19
+ - Trả về biểu diễn đã tạo hoặc đã cập nhật, hoặc theo quy ước hiện có.
20
+ - Dùng ID mờ hoặc không tăng tuần tự trong URL khi việc dò tuần tự làm lộ thông tin.
21
+
22
+ ## Status code
23
+
24
+ | Tình huống | Code |
25
+ | --- | --- |
26
+ | Đọc hoặc cập nhật thành công | 200 |
27
+ | Đã tạo | 201, kèm header Location nếu dự án dùng |
28
+ | Nhận để xử lý bất đồng bộ | 202, kèm cách poll trạng thái |
29
+ | Thành công, không có body | 204 |
30
+ | Input sai dạng hoặc không hợp lệ | 400 hoặc 422, theo quy ước của dự án |
31
+ | Chưa authenticate | 401 |
32
+ | Đã authenticate nhưng không được phép | 403, hoặc 404 để không tiết lộ sự tồn tại |
33
+ | Không tìm thấy | 404 |
34
+ | Xung đột trạng thái, trùng lặp, lệch version | 409 (hoặc 412 cho precondition) |
35
+ | Bị giới hạn tần suất | 429, kèm Retry-After khi biết |
36
+ | Server lỗi bất ngờ | 500 |
37
+ | Dependency không khả dụng hoặc timeout | 502, 503, hay 504 |
38
+
39
+ Không bao giờ trả 200 với body là lỗi. Không bao giờ trả 500 cho input client sai.
40
+
41
+ ## Body của lỗi
42
+
43
+ Dùng một hình dạng lỗi duy nhất ở mọi nơi. Nếu dự án chưa có, chỉ cần một code ổn
44
+ định máy đọc được, một message cho người, và chi tiết field tùy chọn, ví dụ
45
+ `{ "error": { "code": "validation_failed", "message": "...", "fields": {...} } }`.
46
+ Một số dự án dùng problem details của RFC 9457; hãy theo cái đang có.
47
+
48
+ ## Phân trang
49
+
50
+ - Phân trang theo cursor (keyset) cho tập dữ liệu lớn hoặc hay thay đổi: trả về một
51
+ cursor `next` mờ, dẫn xuất từ khóa sắp xếp cộng một khóa phá thế bằng duy nhất.
52
+ - Phân trang theo offset chỉ dùng cho tập nhỏ, ổn định, hoặc khi client cần số trang;
53
+ nó chậm dần và bỏ sót hoặc lặp dòng khi có ghi đồng thời.
54
+ - Luôn chặn kích thước trang ở phía server và áp một giá trị mặc định.
55
+ - Làm thứ tự sắp xếp tường minh và tất định.
56
+ - Chỉ trả tổng số khi nó rẻ hoặc bắt buộc; việc đếm có thể đắt.
57
+
58
+ ## Lọc và sắp xếp
59
+
60
+ - Lập whitelist các field được lọc và được sắp xếp; đừng bao giờ truyền input thô vào truy vấn.
61
+ - Từ chối các tham số lọc hay sắp xếp không nhận biết được, hoặc bỏ qua chúng, theo quy ước dự
62
+ án.
63
+
64
+ ## Idempotency
65
+
66
+ - PUT và DELETE phải idempotent theo thiết kế.
67
+ - Với POST tạo mới hoặc thu phí, hãy nhận một header idempotency key khi client có
68
+ thể retry. Lưu key cùng dấu vết của request và response; phát lại response đã lưu
69
+ khi gặp lại; từ chối một key dùng lại với body khác (409 hoặc 422).
70
+ - Cho key đã lưu một thời hạn. Giới hạn phạm vi theo từng client hoặc user.
71
+ - Handler của webhook và job dedupe theo ID của event hoặc message.
72
+
73
+ ## Đồng thời
74
+
75
+ - Với các cập nhật có thể đua nhau, dùng optimistic concurrency: một ETag hoặc field
76
+ version, kèm If-Match hoặc version trong body, và 409 hoặc 412 khi lệch.
77
+
78
+ ## Versioning
79
+
80
+ - Ưu tiên thay đổi chỉ thêm vào, tương thích ngược: field tùy chọn mới, endpoint mới.
81
+ - Thay đổi phá vỡ (bỏ hoặc đổi tên field, đổi kiểu hay ý nghĩa, siết validation) cần
82
+ quyết định của owner và một đường migration.
83
+ - Theo lược đồ versioning của dự án (tiền tố path, header, hay không có). Đừng đưa vào
84
+ một lược đồ mới mà không có quyết định.
85
+ - Client nên bỏ qua field không biết; đừng dựa vào thứ tự field.
86
+
87
+ ## Validate request
88
+
89
+ - Validate ở biên: kiểu, field bắt buộc, khoảng giá trị, độ dài, định dạng, thuộc tập
90
+ enum, và kích thước body tối đa.
91
+ - Dùng validator hoặc library schema hiện có của dự án; đừng thêm cái khác.
92
+ - Parse thành một giá trị có kiểu hoặc đã chuẩn hóa, rồi chỉ truyền giá trị đó vào trong.
93
+ - Từ chối field không biết khi mass assignment là rủi ro (ví dụ client tự đặt `role`
94
+ hay `ownerId`); đừng bao giờ bind body của request thẳng vào model lưu trữ.
95
+ - Trả về tất cả lỗi field một lượt khi khả thi.
96
+ - Validation không phải authorization; kiểm tra quyền riêng.
@@ -0,0 +1,78 @@
1
+ # Authentication và authorization
2
+
3
+ Đọc khi chạm vào login, session, token, OAuth/OIDC, lưu trữ password, hoặc
4
+ kiểm tra quyền.
5
+
6
+ Dùng library hoặc provider auth hiện có của dự án. Tự viết mật mã, xử lý session, hay
7
+ parse token bằng tay là ngoài phạm vi; thay vào đó hãy đề xuất một library đã được
8
+ thẩm định cho owner. Thay đổi về auth xứng đáng có một lượt security-review.
9
+
10
+ ## Session so với token
11
+
12
+ | | Session phía server | Token tự chứa (ví dụ JWT) |
13
+ | --- | --- | --- |
14
+ | Trạng thái | Bản ghi session trong một store; cookie giữ ID | Claim nằm trong token; xác minh bằng chữ ký |
15
+ | Thu hồi | Xóa bản ghi | Khó; cần hạn ngắn, deny list, hoặc xoay refresh token |
16
+ | Phù hợp | App trình duyệt trên một site | Service-to-service, API dùng bởi nhiều client |
17
+
18
+ - Session trình duyệt: cookie với `HttpOnly`, `Secure`, `SameSite=Lax` hoặc `Strict`,
19
+ thời hạn có giới hạn, và một session ID mới sau khi login hay đổi đặc quyền.
20
+ - Request làm thay đổi trạng thái mà authenticate bằng cookie cần bảo vệ CSRF
21
+ (SameSite cộng một token hoặc kiểm tra origin, theo quy ước của dự án).
22
+ - Token: xác minh chữ ký, thuật toán (đừng bao giờ nhận `none` hay một thuật toán
23
+ ngoài dự kiến), issuer, audience, và hạn dùng ở mọi request. Giữ access token
24
+ sống ngắn; xoay refresh token và phát hiện việc dùng lại.
25
+ - Đừng lưu token ở những nơi script bị tiêm có thể đọc, nếu dự án có thể dùng cookie
26
+ HttpOnly thay thế.
27
+
28
+ ## Lưu trữ password
29
+
30
+ - Hash bằng một hàm hash password chậm, có salt: Argon2id, scrypt, hay bcrypt, qua
31
+ library hiện có của dự án. Đừng bao giờ dùng hash nhanh (MD5, SHA-1, SHA-256
32
+ thuần), đừng bao giờ dùng mã hóa có thể giải ngược.
33
+ - So sánh bằng hàm verify của library (thời gian hằng).
34
+ - Hash lại khi login nếu tham số đã được nâng.
35
+ - Giới hạn tần suất cho endpoint login và reset; trả cùng một response cho user không
36
+ tồn tại và cho sai password.
37
+ - Token reset: ngẫu nhiên, dùng một lần, hạn ngắn, lưu dạng đã hash.
38
+
39
+ ## OAuth 2.0 và OIDC (mức tổng quan)
40
+
41
+ - Đăng nhập web và mobile: authorization code flow với PKCE. Validate `state` (CSRF)
42
+ và, với OIDC, `nonce`. Đừng dùng implicit flow.
43
+ - Service-to-service: client credentials flow với credential có scope lấy từ config.
44
+ - ID token của OIDC định danh user với client; access token cho phép gọi API. Đừng
45
+ dùng ID token làm access token cho API.
46
+ - Đăng ký redirect URI chính xác; đừng bao giờ nhận một đích redirect từ input của
47
+ user mà không có allowlist.
48
+ - Map danh tính bên ngoài sang user nội bộ theo subject ID ổn định của provider cộng
49
+ issuer, không chỉ theo email.
50
+
51
+ ## Đặt authorization ở đâu
52
+
53
+ - Authenticate ở biên (middleware hoặc tương đương) và gắn một danh tính vào context
54
+ của request.
55
+ - Authorize tại nơi đã biết resource: sau khi load nó, kiểm tra người gọi được phép
56
+ tác động lên chính bản ghi đó (chủ sở hữu, tenant, role, hay policy). Chỉ kiểm tra
57
+ role ở mức route thì không chặn được việc truy cập bản ghi của user khác (IDOR).
58
+ - Giới hạn truy vấn theo tenant hoặc chủ sở hữu ngay trong lớp truy cập dữ liệu khi
59
+ dự án là multi-tenant, để một lần quên kiểm tra vẫn fail an toàn.
60
+ - Mặc định từ chối. Endpoint mới không có policy tường minh thì phải không tới được.
61
+ - Giữ việc kiểm tra policy ở một chỗ mà dự án đã dùng (một module policy, decorator,
62
+ hay guard) thay vì rải rác các câu điều kiện.
63
+ - Background job và lời gọi nội bộ hành động với một danh tính hoặc service account
64
+ tường minh; ghi lại nó trong audit log ở nơi dự án lưu chúng.
65
+
66
+ ## Secret và config
67
+
68
+ - Khóa ký, client secret, và giá trị pepper đến từ cơ chế secret của dự án. Đừng đọc,
69
+ in, hay commit giá trị của chúng; test dùng khóa test riêng hoặc fake.
70
+ - Đừng bao giờ log credential, token, session ID, hay link reset.
71
+
72
+ ## Những kiểm tra cần thêm
73
+
74
+ - Request chưa authenticate bị từ chối (401).
75
+ - User đã authenticate nhưng không có quyền bị từ chối (403 hoặc 404).
76
+ - User A không đọc hay sửa được resource của user B.
77
+ - Token hết hạn, bị sửa, hay sai audience bị từ chối.
78
+ - Logout hoặc thu hồi thực sự kết thúc quyền truy cập.
@@ -0,0 +1,86 @@
1
+ # Xử lý lỗi
2
+
3
+ Đọc khi map lỗi sang response, thêm retry hay timeout, hoặc quyết định
4
+ log những gì.
5
+
6
+ ## Phân loại lỗi
7
+
8
+ Phân loại mọi thất bại trước khi quyết định xử lý thế nào.
9
+
10
+ | Lớp | Ví dụ | Xử lý | Response thường dùng |
11
+ | --- | --- | --- | --- |
12
+ | Input không hợp lệ | sai kiểu, thiếu field | từ chối ở biên | 400/422 |
13
+ | Chưa authenticate / bị cấm | thiếu token, sai chủ sở hữu | từ chối, không lộ chi tiết | 401/403/404 |
14
+ | Không tìm thấy | ID không biết | lỗi nghiệp vụ | 404 |
15
+ | Xung đột | trùng lặp, version cũ, chuyển trạng thái không hợp lệ | lỗi nghiệp vụ | 409/412 |
16
+ | Tần suất hoặc quota | client vượt giới hạn | từ chối kèm gợi ý | 429 |
17
+ | Dependency lỗi tạm thời | timeout, mất kết nối, upstream 503 | retry nếu idempotent, nếu không thì đẩy ra | 502/503/504 |
18
+ | Dependency lỗi vĩnh viễn | upstream trả 4xx, config sai | đừng retry; báo động | 500/502 |
19
+ | Bug / vỡ bất biến | null ở chỗ không thể null | fail nhanh, log kèm ngữ cảnh | 500 |
20
+
21
+ - Biểu diễn các thất bại nghiệp vụ dự kiến thành lỗi có kiểu hoặc giá trị kết quả,
22
+ theo mẫu của dự án (exception kèm code, error value trong Go, result type).
23
+ - Đừng dùng exception cho luồng điều khiển bình thường ở nơi dự án không làm vậy.
24
+ - Đừng bao giờ lặng lẽ nuốt một lỗi. Hãy xử lý nó, bọc nó kèm ngữ cảnh rồi đẩy lên,
25
+ hoặc log nó ở biên nơi nó kết thúc.
26
+
27
+ ## Map sang response
28
+
29
+ - Map lỗi sang response ở một chỗ (error middleware, exception handler, hay một
30
+ helper dùng chung), không phải trong từng handler.
31
+ - Trả về hình dạng lỗi chuẩn của dự án với một code ổn định.
32
+ - Không phơi nội bộ: không stack trace, SQL, đường dẫn file, hay body của upstream.
33
+ - Đưa một request ID hoặc correlation ID vào response và vào log để có thể truy vết
34
+ một báo cáo.
35
+ - Lỗi không biết trở thành một 500 chung và được log đầy đủ ở phía server.
36
+
37
+ ## Timeout
38
+
39
+ - Mọi lời gọi ra ngoài (HTTP, database, cache, queue) đều có timeout. Dùng mặc định
40
+ đã cấu hình của client nếu dự án có; nếu không, hãy đề xuất một giá trị.
41
+ - Lan truyền deadline hoặc tín hiệu hủy của request (context trong Go, AbortSignal
42
+ trong Node, timeout hay task cancellation trong Python) để công việc dừng khi người
43
+ gọi đã bỏ cuộc.
44
+ - Timeout bên trong phải ngắn hơn timeout bên ngoài.
45
+
46
+ ## Retry
47
+
48
+ - Chỉ retry các thất bại tạm thời của thao tác idempotent, hoặc thao tác đã được làm
49
+ cho idempotent bằng một key.
50
+ - Giới hạn số lần thử (một số nhỏ), dùng exponential backoff kèm jitter, và tôn trọng
51
+ Retry-After.
52
+ - Chỉ retry ở một lớp; retry xếp lồng nhau nhân tải lên.
53
+ - Đừng retry lỗi validation, auth, hay các lỗi vĩnh viễn khác.
54
+ - Với một dependency cứ fail liên tục, dùng circuit breaker hoặc fallback của dự án
55
+ nếu có; đừng thêm library mới mà không có quyết định.
56
+ - Background job: sau lần thử cuối, chuyển sang trạng thái thất bại hoặc dead-letter
57
+ queue kèm lý do; đừng lặp mãi.
58
+
59
+ ## Thất bại một phần
60
+
61
+ - Giữ transaction database ngắn và cục bộ. Đừng gọi service bên ngoài bên trong nó.
62
+ - Khi một lần ghi database và một hiệu ứng bên ngoài (message, email, thanh toán)
63
+ đều phải xảy ra, dùng outbox của dự án hoặc một bước bù; nêu rõ khoảng trống nếu
64
+ không có cả hai.
65
+ - Làm handler an toàn khi chạy lại.
66
+
67
+ ## Log mà không lộ secret
68
+
69
+ - Log ở biên nơi một lỗi được xử lý, một lần, với: code lỗi, message, request ID,
70
+ thao tác, các ID không nhạy cảm liên quan, và chuỗi nguyên nhân.
71
+ - Dùng logger và field có cấu trúc của dự án; khớp với các level đang có (lỗi client
72
+ thường là info hoặc warn, lỗi server là error).
73
+ - Đừng bao giờ log: password, token, API key, session ID, header authorization, số
74
+ thẻ đầy đủ, secret từ config, hay toàn bộ body request có thể chứa chúng.
75
+ - Che hoặc bỏ dữ liệu cá nhân (email, điện thoại, địa chỉ) trừ khi policy của dự án
76
+ cho phép.
77
+ - Kiểm tra rằng message lỗi dựng từ response của upstream không vọng lại credential.
78
+ - Đừng log ở level error cho những lỗi client dự kiến; nó che mất sự cố thật.
79
+
80
+ ## Những kiểm tra cần thêm
81
+
82
+ - Mỗi lớp lỗi đã map trả về đúng status và code đã ghi trong tài liệu.
83
+ - Một exception bất ngờ trả về 500 chung mà không có chi tiết nội bộ.
84
+ - Một dependency bị timeout tạo ra response đã ghi trong tài liệu trong hạn deadline.
85
+ - Retry dừng sau giới hạn và không retry các lỗi vĩnh viễn.
86
+ - Log của một request auth thất bại không chứa token hay password.
@@ -0,0 +1,81 @@
1
+ # Test backend
2
+
3
+ Đọc khi chọn test handler, service, integration, hay contract cho một thay đổi
4
+ backend. Việc cần test những gì nói chung thuộc test-strategy; đây nói về cách làm ở từng seam.
5
+
6
+ Dùng test runner, fixture và helper hiện có của dự án (ví dụ Jest hay Vitest cho
7
+ Node/TypeScript, pytest cho Python, `go test` cho Go). Đừng thêm framework test hay
8
+ công cụ container mà không có quyết định của owner.
9
+
10
+ ## Chọn seam
11
+
12
+ | Seam | Chứng minh | Thay thế bằng |
13
+ | --- | --- | --- |
14
+ | Unit service / nghiệp vụ | quy tắc nghiệp vụ, ca biên, map lỗi | fake cho store, clock, client |
15
+ | Handler / route | parsing, validation, status code, nối auth, hình dạng lỗi | server in-process; service thật hoặc fake |
16
+ | Integration | truy vấn, transaction, constraint, migration | database thật cùng engine |
17
+ | Contract | hình dạng request và response đã thống nhất với bên tiêu thụ hoặc bên cung cấp | contract đã ghi lại hoặc dựa trên schema |
18
+ | Đầu-cuối | một luồng quan trọng xuyên nhiều process | chỉ trong môi trường test |
19
+
20
+ Đặt phần lớn các ca ở seam rẻ nhất mà vẫn chạy qua nguyên nhân thật. Một bug truy vấn
21
+ cần engine database thật; một quy tắc validation thì không.
22
+
23
+ ## Test service
24
+
25
+ - Tiêm dependency (store, clock, bộ sinh ID, client gọi ra ngoài) để test kiểm soát
26
+ được chúng. Một fake viết tay có hành vi thật hơn một mock chỉ ghi lại lời gọi.
27
+ - Phủ từng ca của contract: thành công, từng lỗi nghiệp vụ, giá trị biên, và việc
28
+ chạy lại idempotent.
29
+ - Đóng băng thời gian và ngẫu nhiên thay vì sleep hay assert theo khoảng.
30
+
31
+ ## Test handler
32
+
33
+ - Chạy handler qua test client in-process của framework (ví dụ request kiểu
34
+ supertest, test client của FastAPI hay Django, `httptest` trong Go).
35
+ - Assert status, code lỗi, và các field body quan trọng; tránh assert toàn bộ body
36
+ khi chỉ vài field là thuộc contract.
37
+ - Test các đường authentication và authorization: thiếu credential, sai user, sai
38
+ tenant, role đủ quyền.
39
+ - Test các ca validation thất bại, kể cả field quá lớn và field không biết.
40
+
41
+ ## Test integration với database thật
42
+
43
+ - Dùng cùng engine và cùng major version như production. SQLite không thay được cho
44
+ hành vi của PostgreSQL hay MySQL (kiểu dữ liệu, locking, lỗi constraint).
45
+ - Chạy nó theo cách dự án đã làm: một test container, một service local, hay một
46
+ service trong CI. Nếu chưa có, hãy đề xuất; đừng tự cài.
47
+ - Áp migration thật lên database test, không dùng schema viết tay.
48
+ - Cô lập các test: một transaction được rollback mỗi test, một schema mới mỗi worker,
49
+ hay truncate giữa các test. Đừng phụ thuộc thứ tự test.
50
+ - Chỉ seed dữ liệu mà một test cần, qua factory hoặc builder, ngay trong test đó.
51
+ - Đừng bao giờ trỏ test vào database dùng chung hay production.
52
+
53
+ ## Dependency gọi ra ngoài
54
+
55
+ - Fake HTTP của bên thứ ba ở biên client (một stub server local hoặc công cụ mock
56
+ HTTP của dự án). Đừng gọi service bên ngoài thật trong test.
57
+ - Test cả response timeout và lỗi từ dependency, không chỉ thành công.
58
+ - Dùng credential test hoặc giá trị giả; đừng bao giờ dùng key thật.
59
+
60
+ ## Background job
61
+
62
+ - Chạy handler trực tiếp với một message; assert hiệu ứng.
63
+ - Chạy nó hai lần với cùng message; assert không có hiệu ứng lặp.
64
+ - Làm handler fail; assert số lần retry và trạng thái thất bại cuối.
65
+
66
+ ## Test contract
67
+
68
+ - Khi một team hay service khác tiêu thụ API, hãy kiểm tra hình dạng đối chiếu với
69
+ schema đã thống nhất (OpenAPI, protobuf, JSON Schema) hoặc consumer contract, dùng
70
+ công cụ hiện có của dự án.
71
+ - Một test contract fail vì thay đổi của bạn nghĩa là một thay đổi phá vỡ; hãy chuyển
72
+ quyết định lên thay vì sửa contract cho pass.
73
+
74
+ ## Vệ sinh
75
+
76
+ - Không sleep để đồng bộ; hãy chờ một điều kiện hoặc dùng clock điều khiển được.
77
+ - Không secret thật, dữ liệu cá nhân, hay dump production trong fixture.
78
+ - Một test mới phải fail khi chưa có thay đổi. Nếu nó pass trước khi sửa, nó không
79
+ chứng minh được thay đổi (xem bug-loop).
80
+ - Giữ thời gian chạy test tương xứng; đánh dấu các test integration chậm theo cách dự
81
+ án đã làm.