@anhlp/alp-core 0.0.0-beta.2 → 0.0.1-beta.10
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/backup.js +106 -4
- package/dist/bridges.d.ts +26 -0
- package/dist/bridges.js +96 -0
- package/dist/gate-ledger.d.ts +30 -0
- package/dist/gate-ledger.js +99 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2 -0
- package/dist/library-edit.d.ts +57 -5
- package/dist/library-edit.js +216 -11
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/migrations.js +1 -1
- package/dist/models.d.ts +74 -0
- package/dist/models.js +67 -1
- package/dist/packaged.d.ts +122 -0
- package/dist/packaged.js +125 -0
- 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 +6 -6
- package/dist/providers.d.ts +4 -5
- package/dist/providers.js +26 -5
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/task-rows.d.ts +5 -0
- package/dist/task-rows.js +1 -1
- package/dist/tasks.d.ts +23 -4
- package/dist/tasks.js +103 -9
- package/dist/types.d.ts +3 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/user-settings.d.ts +2 -0
- package/dist/user-settings.js +40 -1
- package/dist/user-worktree.d.ts +29 -0
- package/dist/user-worktree.js +242 -0
- package/dist/validation.d.ts +1 -0
- package/dist/validation.js +35 -13
- package/package.json +34 -2
- package/src/backup.js +106 -5
- package/src/bridges.js +113 -0
- package/src/gate-ledger.js +125 -0
- package/src/index.js +1 -0
- package/src/library-edit.js +227 -12
- package/src/library.js +96 -6
- package/src/migrations.js +1 -1
- package/src/models.js +87 -1
- package/src/packaged.js +207 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +7 -7
- package/src/providers.js +23 -7
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/task-rows.js +1 -1
- package/src/tasks.d.ts +23 -4
- package/src/tasks.js +137 -10
- package/src/types.d.ts +3 -0
- package/src/upgrade.js +54 -6
- package/src/user-settings.d.ts +2 -0
- package/src/user-settings.js +51 -1
- package/src/user-worktree.js +259 -0
- package/src/validation.d.ts +1 -0
- package/src/validation.js +43 -14
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -141
- 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 +34 -0
- package/templates/skills/curate/SKILL.md +36 -0
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Sơ đồ
|
|
2
|
+
|
|
3
|
+
Đọc khi thêm hoặc cập nhật một sơ đồ Mermaid trong tài liệu kiến trúc.
|
|
4
|
+
|
|
5
|
+
## Quy tắc
|
|
6
|
+
- Mỗi node ứng với một module, package, service hay đường dẫn thật; đặt đường dẫn vào
|
|
7
|
+
nhãn hoặc vào một ghi chú bên dưới sơ đồ.
|
|
8
|
+
- Mỗi mũi nối ứng với một import, lời gọi, message, route hay mục config mà bạn dẫn nguồn được.
|
|
9
|
+
- Nhiều nhất khoảng 12 node; hãy tách theo ranh giới chứ đừng thu nhỏ nhãn.
|
|
10
|
+
- Một sơ đồ, một câu hỏi: cấu trúc, đường đi của một request, hoặc cách triển khai. Không gộp
|
|
11
|
+
cả ba.
|
|
12
|
+
- Ghi nhãn mũi nối bằng protocol hoặc động từ khi điều đó không hiển nhiên.
|
|
13
|
+
- Không tô kiểu, màu hay icon trừ khi tài liệu của project đã dùng chúng.
|
|
14
|
+
- Sinh lại từ code khi ranh giới đổi; xoá sơ đồ không ai bảo trì.
|
|
15
|
+
- Các cạnh chưa kiểm chứng dùng mũi nối nét đứt kèm ghi chú "Unverified".
|
|
16
|
+
|
|
17
|
+
## Flowchart: phụ thuộc giữa các module
|
|
18
|
+
```mermaid
|
|
19
|
+
flowchart LR
|
|
20
|
+
cli["cli (packages/cli)"] --> core["core (packages/core)"]
|
|
21
|
+
daemon["daemon (packages/daemon)"] --> core
|
|
22
|
+
daemon --> runtime["runtime (packages/runtime)"]
|
|
23
|
+
runtime -.-> core
|
|
24
|
+
```
|
|
25
|
+
Ghi chú: cạnh nét đứt đánh dấu một import chỉ thấy trong test (Unverified với code runtime).
|
|
26
|
+
|
|
27
|
+
## Sequence: đường đi của một request
|
|
28
|
+
```mermaid
|
|
29
|
+
sequenceDiagram
|
|
30
|
+
participant C as Client
|
|
31
|
+
participant R as Router (src/routes/orders.ts)
|
|
32
|
+
participant S as OrderService (src/orders/service.ts)
|
|
33
|
+
participant D as DB
|
|
34
|
+
C->>R: POST /orders
|
|
35
|
+
R->>S: create(input)
|
|
36
|
+
S->>D: insert order
|
|
37
|
+
D-->>S: id
|
|
38
|
+
S-->>R: Order
|
|
39
|
+
R-->>C: 201 Created
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Góc nhìn container (kiểu C4, vẽ bằng flowchart)
|
|
43
|
+
```mermaid
|
|
44
|
+
flowchart TB
|
|
45
|
+
user([User])
|
|
46
|
+
subgraph system [Shop system]
|
|
47
|
+
web["web app (apps/web)"]
|
|
48
|
+
api["api (apps/api)"]
|
|
49
|
+
db[("Postgres, from docker-compose.yml")]
|
|
50
|
+
end
|
|
51
|
+
pay["Payment provider (external)"]
|
|
52
|
+
user --> web --> api --> db
|
|
53
|
+
api -->|HTTPS| pay
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Kiểm một sơ đồ
|
|
57
|
+
- Với mỗi node, xác nhận đường dẫn tồn tại.
|
|
58
|
+
- Với mỗi cạnh, tìm dòng import, lời gọi hay config; dẫn nó trong phần chữ xung quanh.
|
|
59
|
+
- Render bằng công cụ tài liệu của project nếu có; nếu không thì soi cú pháp bằng mắt dựa trên
|
|
60
|
+
các ví dụ này và giữ sơ đồ đơn giản.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Quy tắc về bằng chứng
|
|
2
|
+
|
|
3
|
+
Đọc khi trích xuất dữ kiện kiến trúc từ một repository và khi dẫn nguồn hoặc đánh dấu chúng.
|
|
4
|
+
|
|
5
|
+
## Dữ kiện đến từ đâu
|
|
6
|
+
| Dữ kiện | Bằng chứng chính |
|
|
7
|
+
|---|---|
|
|
8
|
+
| Ngôn ngữ, runtime, package | Manifest và lockfile (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`) |
|
|
9
|
+
| Đơn vị runtime và cách khởi động | Entry point (`bin`, `main`, `scripts`), Dockerfile, config process hoặc service |
|
|
10
|
+
| Ranh giới module | Config workspace, export của package, file khai báo sở hữu thư mục, quy tắc lint về import |
|
|
11
|
+
| Phụ thuộc giữa các module | Câu lệnh import và đồ thị build; ưu tiên output của công cụ dựng đồ thị đang có |
|
|
12
|
+
| Bề mặt HTTP hoặc RPC | File đăng ký route, file OpenAPI hoặc proto, test của handler |
|
|
13
|
+
| Hình dạng dữ liệu | Schema, migration, định nghĩa type, validator |
|
|
14
|
+
| Hệ thống bên ngoài | Cấu hình client, các chỗ đọc biến môi trường, manifest triển khai |
|
|
15
|
+
| Quy ước | Mẫu lặp lại ở ba chỗ trở lên, config lint và format |
|
|
16
|
+
| Quyết định | ADR đang có, commit message phát biểu một lựa chọn, xác nhận từ người dùng |
|
|
17
|
+
|
|
18
|
+
Test là bằng chứng về hành vi mong muốn; config là bằng chứng về cái đang được triển khai chỉ
|
|
19
|
+
khi đường deploy thực sự đọc nó.
|
|
20
|
+
|
|
21
|
+
## Các bước trích xuất
|
|
22
|
+
1. Bắt đầu từ entry point rồi lần theo import ra ngoài; đừng bắt đầu từ tên thư mục.
|
|
23
|
+
2. Đếm trước khi khái quát: một lần xuất hiện là một ví dụ, không phải một quy ước.
|
|
24
|
+
3. Dùng câu lệnh chỉ đọc (tìm, liệt kê, công cụ dựng đồ thị hay build của chính project); đừng
|
|
25
|
+
cài thêm bộ phân tích.
|
|
26
|
+
4. Ghi lại câu lệnh và kết quả cho mọi dữ kiện không hiển nhiên.
|
|
27
|
+
|
|
28
|
+
## Cách dẫn nguồn
|
|
29
|
+
- Trong dòng: `The daemon owns session state (packages/daemon/src/sessions.js).`
|
|
30
|
+
- Kèm symbol: `(packages/core/src/tasks.js, createTask)`.
|
|
31
|
+
- Kèm số dòng chỉ khi chúng ổn định: `(src/router.ts:40-62)`.
|
|
32
|
+
- Nhiều nguồn: liệt kê nguồn trực tiếp nhất trước.
|
|
33
|
+
- Đường dẫn tương đối từ root của repository; không dùng đường dẫn tuyệt đối hay gắn với một
|
|
34
|
+
máy.
|
|
35
|
+
|
|
36
|
+
## Đánh dấu điều chưa biết
|
|
37
|
+
- Trong dòng: `Unverified: the worker appears to retry three times (src/worker.js:88); no test covers it.`
|
|
38
|
+
- Cuối mục: danh sách `Open questions`, mỗi mục kèm người có thể trả lời và bằng chứng nào sẽ
|
|
39
|
+
giải quyết nó.
|
|
40
|
+
- Không bao giờ nâng một phát biểu chưa kiểm chứng lên thành dữ kiện mà không có bằng chứng
|
|
41
|
+
mới.
|
|
42
|
+
|
|
43
|
+
## Dấu hiệu đáng ngại
|
|
44
|
+
- Một phát biểu không có đường dẫn, hoặc một đường dẫn không còn tồn tại.
|
|
45
|
+
- Những chữ như "should", "will", "designed to" dùng để mô tả hành vi hiện tại.
|
|
46
|
+
- Một sơ đồ hay danh sách module sao từ tài liệu cũ mà không kiểm lại cây nguồn.
|
|
47
|
+
- Config cho một service mà không có gì khởi động hay triển khai.
|
|
48
|
+
- Quy ước được ghi từ một file duy nhất, hoặc từ một style guide mà code bỏ ngoài tai.
|
|
49
|
+
- Tên host nội bộ, secret hay dữ liệu khách hàng: hãy xoá chúng.
|
|
@@ -1,44 +1,45 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: bug-loop
|
|
3
|
-
description:
|
|
3
|
+
description: Chẩn đoán một bug hay regression bằng một vòng lặp phản hồi tái lập được, các cách giải thích cạnh tranh nhau, và bản sửa đã được kiểm chứng. Dùng khi test fail, khi hành vi sai, hoặc khi có regression về hiệu năng; việc được giao ở dạng chỉ đọc thì dừng trước khi sửa artifact của project.
|
|
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
|
-
so
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
test
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
6
|
+
# Dựng một vòng lặp fail trước, rồi sửa nguyên nhân
|
|
7
|
+
|
|
8
|
+
Bắt đầu từ hành vi được báo và phạm vi được giao. Tìm câu lệnh, request, bản replay
|
|
9
|
+
hay test nhỏ nhất mà vẫn hữu ích để phân biệt bug với hành vi đúng. Chạy nó và ghi lại
|
|
10
|
+
kết quả thực tế trước khi tuyên bố đã tái lập được. Với lỗi chập chờn, hãy ghi lại điều
|
|
11
|
+
kiện, seed khi có, và tần suất fail quan sát được.
|
|
12
|
+
|
|
13
|
+
Nếu việc tái lập cần credential, phần cứng, dữ liệu hay một hành động của người dùng mà
|
|
14
|
+
bạn không có, hãy báo đúng chỗ thiếu đó cho agent giao việc; main lo phần giao tiếp với
|
|
15
|
+
người dùng. Vẫn tiếp tục điều tra hữu ích trong phạm vi, nhưng hãy ghi rõ giả thuyết nào
|
|
16
|
+
chưa được xác nhận. Đừng tuyên bố một bản sửa đã được kiểm chứng khi chưa có một phép
|
|
17
|
+
kiểm quan sát được và có ý nghĩa.
|
|
18
|
+
|
|
19
|
+
Thu nhỏ bản tái lập mà không làm mất lỗi. Ở chỗ nguyên nhân còn chưa chắc, hãy dựng các
|
|
20
|
+
cách giải thích cạnh tranh nhau, mỗi cách kèm một dự đoán quan sát được. Thăm dò vài điểm
|
|
21
|
+
phân biệt được chúng; đổi mỗi lần một biến. Ưu tiên bằng chứng đo được hơn là chồng thêm
|
|
22
|
+
các cách lách cho cùng một triệu chứng chưa giải thích được.
|
|
23
|
+
|
|
24
|
+
Dùng không gian scratch riêng biệt cho các thí nghiệm dùng một lần. Việc được giao ở dạng
|
|
25
|
+
chỉ đọc có thể xem xét và chẩn đoán; nó không cho phép sửa code của project để chèn công
|
|
26
|
+
cụ đo. Với việc về hiệu năng, hãy so các khối việc tương đương và ghi lại các điều kiện
|
|
27
|
+
liên quan, để một chênh lệch thời gian không bị hiểu nhầm thành cải thiện có nhân quả.
|
|
28
|
+
|
|
29
|
+
Khi nguyên nhân đã được xác lập và bạn đã được cấp quyền ghi:
|
|
30
|
+
|
|
31
|
+
1. Đặt một phép kiểm regression ngay tại đường ráp tái lập được lỗi thực tế.
|
|
32
|
+
2. Xác nhận phép kiểm đó fail đúng vì lý do đã báo trên hành vi bị lỗi.
|
|
33
|
+
3. Làm bản sửa nhỏ nhất mà vẫn nhất quán với contract dự kiến.
|
|
34
|
+
4. Chạy lại phép kiểm đó, rồi các phép kiểm liên quan xung quanh và tình huống ban đầu.
|
|
35
|
+
5. Bỏ công cụ đo tạm thời và hoàn lại mọi chỗ cố tình chèn lỗi.
|
|
36
|
+
|
|
37
|
+
Đọc [test proof](references/test-proof.md) khi thiết kế/review test regression, hoặc khi
|
|
38
|
+
nó pass ngay trước lúc sửa. Đừng làm yếu kỳ vọng, đừng bỏ qua phép kiểm đang fail, và đừng
|
|
39
|
+
mock cho hành vi biến đi để tạo ra một lần pass. Một yêu cầu đã thay đổi phải được xác lập
|
|
40
|
+
độc lập với cái mà implementation hiện trả về.
|
|
41
|
+
|
|
42
|
+
Trả về câu lệnh tái lập và kết quả, nguyên nhân đã xác lập hoặc các giả thuyết còn lại,
|
|
43
|
+
artifact đã thay đổi, phép kiểm trước/sau, các giới hạn, và rủi ro chưa xử lý.
|
|
44
|
+
Peer trả về cho lead; lead trả về cho main. Điều tra ở dạng chỉ đọc trả về bằng chứng
|
|
45
|
+
chẩn đoán và một bản sửa đề xuất, không phải một thay đổi code tưởng tượng.
|
|
@@ -1,25 +1,27 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Bằng chứng cho một bản sửa regression
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Chọn một biên quan sát được, đủ gần để khoanh được lỗi nhưng đủ rộng để kích hoạt đúng
|
|
4
|
+
nguyên nhân thật của nó. Một unit test của một bên gọi không thể xác lập một bug phụ
|
|
5
|
+
thuộc vào thứ tự giữa nhiều bên gọi.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
Hành vi mong đợi đến từ yêu cầu của người dùng, từ một contract được hỗ trợ, hoặc từ các
|
|
8
|
+
ví dụ suy ra một cách độc lập. Đừng tính kết quả mong đợi bằng chính implementation đang
|
|
9
|
+
được kiểm. Chỉ mock các biên bên ngoài ở chỗ việc mock vẫn giữ được hành vi được tuyên bố
|
|
10
|
+
nằm trong phạm vi kiểm.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Hãy mô tả bằng chứng cho chính xác:
|
|
13
13
|
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
|
|
14
|
+
- Chỉ xanh: phép kiểm hiện tại pass; chỉ riêng điều này không cho thấy có phủ regression.
|
|
15
|
+
- Đỏ -> xanh: phép kiểm fail trên hành vi bị lỗi và pass sau khi sửa.
|
|
16
|
+
- Chèn lỗi: ở chỗ rủi ro biện minh được, hãy dựng lại đúng khuyết điểm đó trong một bản
|
|
17
|
+
sao riêng, xác nhận nó fail, hoàn lại bản sửa, rồi xác nhận nó thành công lần nữa.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
Chèn lỗi là tuỳ chọn, trừ khi việc được giao bắt buộc. Đừng bao giờ sửa checkout của người
|
|
20
|
+
ghi khác, đừng bỏ đi công việc không liên quan, và đừng để lại code cố tình làm sai trong
|
|
21
|
+
sản phẩm giao. Hãy nêu rõ như một giới hạn khi không chạy được bản trước khi sửa hoặc khi
|
|
22
|
+
thiếu đường ráp để test.
|
|
22
23
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
Giữ lại đúng các câu lệnh, kết quả, và các điều kiện môi trường liên quan. Ảnh chụp màn
|
|
25
|
+
hình, log và hành vi quan sát bằng tay có thể bổ trợ cho test; đừng dán nhãn chúng thành
|
|
26
|
+
bằng chứng tự động. Một phép kiểm pass và một quyết định nghiệm thu độc lập là hai chuyện
|
|
27
|
+
khác nhau.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: compact
|
|
3
|
+
description: "Viết checkpoint có cấu trúc trước khi compact context của main, để sau khi nén vẫn tiếp tục đúng việc. Dùng khi runtime báo context gần đầy (khoảng 70%), khi người dùng yêu cầu compact, hoặc trước khi chuyển phiên."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Compact
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
- Runtime báo context dùng khoảng 70% hoặc hơn, hay yêu cầu viết checkpoint.
|
|
10
|
+
- Người dùng yêu cầu compact.
|
|
11
|
+
- Trước khi kết thúc hoặc chuyển phiên.
|
|
12
|
+
|
|
13
|
+
Không compact khi đang giữ lượt (alp_wait, alp_ask, delegate wait), hoặc khi đang viết dở câu trả lời. Phải trả lời người dùng trước.
|
|
14
|
+
|
|
15
|
+
## Quy trình
|
|
16
|
+
1. **Kiểm thực tế, không chép trí nhớ.** Đọc alp_task ready/list và alp_board. Với PR/CI liên quan, chạy gh pr view/checks ngay trong lượt.
|
|
17
|
+
2. **Viết checkpoint theo đúng các mục sau** (ngắn, có ID, có giờ):
|
|
18
|
+
- **Người dùng và ngôn ngữ:** profile (Phở/Cafe), ngôn ngữ trả lời.
|
|
19
|
+
- **Assignment đang chạy:** assignmentId, agent, taskId, worktree hoặc nhánh, ETA, note cuối kèm giờ.
|
|
20
|
+
- **Task và gate:** task đang làm hoặc chờ review; gate đang mở kèm nội dung; gate đã có quyết định nhưng chưa gỡ.
|
|
21
|
+
- **Quyết định của người dùng:** trích nguyên văn, kèm giờ và task nhận quyết định đó.
|
|
22
|
+
- **Câu hỏi đang chờ người dùng:** câu hỏi nào, ở gate nào.
|
|
23
|
+
- **PR/CI:** số PR, head SHA, trạng thái check đã kiểm lúc nào, watcher nền (job id) nếu có.
|
|
24
|
+
- **Rủi ro và giới hạn còn mở:** từng mục, kèm task theo dõi.
|
|
25
|
+
- **Bước tiếp theo:** theo thứ tự, ai làm.
|
|
26
|
+
3. **Không đưa vào checkpoint:** bài học, skill, nội dung task đầy đủ (đã lưu ngoài context), log dài, secret.
|
|
27
|
+
4. Gửi checkpoint cho runtime theo yêu cầu, hoặc ghi alp_pin/task note nếu compact thủ công. Sau đó báo người dùng một dòng: "Em đã compact context; checkpoint giữ X assignment, Y gate, Z quyết định."
|
|
28
|
+
|
|
29
|
+
## Kiểm chứng
|
|
30
|
+
- Mọi assignment đang chạy đều có ID.
|
|
31
|
+
- Mọi gate mở và mọi câu hỏi đang chờ đều có trong checkpoint.
|
|
32
|
+
- Quyết định của người dùng được trích nguyên văn, không diễn giải.
|
|
33
|
+
- Trạng thái PR/CI ghi rõ thời điểm đã kiểm.
|
|
34
|
+
- Sau compact, lượt đầu tiên đọc lại alp_task và gh trước khi báo trạng thái.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: curate
|
|
3
|
+
description: "Rà soát toàn bộ bài học (lesson) và skill: gộp lesson trùng, rút gọn lesson dài, bỏ lesson đã có skill thay, đề xuất cho nghỉ skill không còn cần, và đề xuất issue cho ALP. Dùng khi người dùng yêu cầu rà soát, hoặc khi lịch curate hằng tháng đánh thức main."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Curate
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
- Người dùng yêu cầu rà soát, dọn dẹp hay rút gọn lesson và skill.
|
|
10
|
+
- Main được đánh thức bởi lịch curate hằng tháng (prompt có `[alp-curate]`).
|
|
11
|
+
|
|
12
|
+
Không làm khi đang giữ một gate hay câu hỏi khác với người dùng; trả lời việc đó trước.
|
|
13
|
+
|
|
14
|
+
## Quy trình
|
|
15
|
+
1. **Đọc hết, không nhớ lại.** Đọc `.alp/lessons.md` của project và `~/.alp/lessons.md` của người dùng; đọc mọi SKILL.md trong `~/.alp/skills`, `.alp/skills` và danh sách skill của từng role (`role-skills.json`).
|
|
16
|
+
2. **Lập đề xuất, mỗi mục một dòng lý do:**
|
|
17
|
+
- **Gộp:** các lesson cùng ý thành một rule.
|
|
18
|
+
- **Rút gọn:** lesson dài hoặc lan man thành một rule ngắn: làm gì, khi nào.
|
|
19
|
+
- **Xóa:** lesson đã được một skill bao trọn (nêu tên skill), hoặc đã lỗi thời.
|
|
20
|
+
- **Thành skill:** 3 lesson trở lên cùng chủ đề thì gom thành skill qua `alp_skill` (truyền `lessons` để bỏ chúng).
|
|
21
|
+
- **Skill không còn cần:** trùng skill khác, không role nào dùng, hay đã lỗi thời. Nêu lý do và đề xuất cho nghỉ qua `alp_skill_retire`.
|
|
22
|
+
- **Đề xuất cho ALP:** lesson hay skill hữu ích cho mọi người dùng, hoặc chỗ ALP còn thiếu.
|
|
23
|
+
3. **Gửi qua cổng duyệt, không hỏi trước trong chat.** Tóm tắt đề xuất trong một tin, rồi gọi ngay các tool bên dưới. Lần duyệt trong tool là lần duyệt duy nhất; người dùng từ chối hay góp ý thì sửa và đề xuất lại.
|
|
24
|
+
4. **Các tool:**
|
|
25
|
+
- Lesson: một lần gọi `alp_lesson_curate` với mọi thay đổi (remove là văn bản đúng nguyên văn; add là rule thay thế khi gộp hoặc rút gọn). ALP hiện toàn bộ thay đổi trong một lần duyệt.
|
|
26
|
+
- Skill mới: `alp_skill`.
|
|
27
|
+
- Skill không còn cần: `alp_skill_retire` từng skill (name, reason). Chỉ khi người dùng duyệt, ALP mới chuyển nó sang `retired-skills` (vẫn giữ, khôi phục được) và bỏ khỏi `role-skills.json`.
|
|
28
|
+
- Issue: `alp_issue` action search target alp trước; chưa có thì create, đã có thì comment. Người dùng duyệt từng bản nháp.
|
|
29
|
+
5. Báo kết quả một đoạn ngắn: đã gộp, rút gọn, xóa bao nhiêu; skill nào được cho nghỉ; issue nào đã tạo.
|
|
30
|
+
|
|
31
|
+
## Kiểm chứng
|
|
32
|
+
- Không sửa hay xóa lesson nào ngoài `alp_lesson_curate`; không sửa file lesson trực tiếp.
|
|
33
|
+
- Mỗi rule sau gộp vẫn giữ đủ ý của các lesson gốc.
|
|
34
|
+
- Mỗi lesson bị xóa vì skill đều nêu đúng tên skill thay nó.
|
|
35
|
+
- Issue không chứa secret, đường dẫn riêng hay nội dung project của người dùng.
|
|
36
|
+
- Không có thay đổi nào khi người dùng chưa duyệt; lesson không tìm thấy được báo lại, không đoán.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: feature-architecture
|
|
3
|
+
description: "Hiện thực một feature mới sao cho nó khớp với các quy tắc kiến trúc, boilerplate và hướng phụ thuộc đang có của project, với một bản thiết kế ngắn trước và các phép kiểm ranh giới sau. Dùng khi thêm feature vào một codebase có tài liệu kiến trúc, ADR, template hoặc một contract về ranh giới. Không dùng cho việc cấu trúc lại mà giữ nguyên hành vi (safe-refactor) hay sửa một regression (bug-loop)."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Kiến trúc feature
|
|
7
|
+
|
|
8
|
+
## Khi dùng
|
|
9
|
+
|
|
10
|
+
- Một feature, endpoint, module hay câu lệnh mới phải đưa được vào một project đã có
|
|
11
|
+
tài liệu kiến trúc, ADR, quy tắc về lớp hoặc package, hay boilerplate cho feature.
|
|
12
|
+
- Một architect hoặc reviewer chỉ đọc được hỏi xem một feature đã lên kế hoạch có khớp
|
|
13
|
+
với kiến trúc của project hay không (chỉ tư vấn).
|
|
14
|
+
|
|
15
|
+
## Không dùng cho
|
|
16
|
+
|
|
17
|
+
- Cấu trúc lại code đang có mà không đổi hành vi: dùng safe-refactor.
|
|
18
|
+
- Tái lập và sửa một bug hay regression: dùng bug-loop.
|
|
19
|
+
- Viết hay sắp xếp lại chính tài liệu kiến trúc: dùng architecture-docs.
|
|
20
|
+
- Chọn một phong cách kiến trúc mới cho project: đó là quyết định của người dùng.
|
|
21
|
+
|
|
22
|
+
## Điều kiện tiên quyết
|
|
23
|
+
|
|
24
|
+
- Một phạm vi được giao (đường dẫn hoặc module) và tiêu chí nghiệm thu lấy từ brief.
|
|
25
|
+
- Quyền đọc ALP.md, hướng dẫn của project, và tài liệu kiến trúc nếu có.
|
|
26
|
+
|
|
27
|
+
## Quy trình
|
|
28
|
+
|
|
29
|
+
1. Đọc ALP.md và hướng dẫn riêng của project; ghi lại câu lệnh build, test, lint và
|
|
30
|
+
kiểm ranh giới.
|
|
31
|
+
2. Đọc các tài liệu kiến trúc liên quan (ví dụ `docs/architecture/`, các ADR, README của
|
|
32
|
+
package). Chỉ đọc phần dính tới các module mà feature này chạm vào.
|
|
33
|
+
3. Liệt kê các quy tắc thành hai nhóm. Ràng buộc cứng: quy tắc phụ thuộc, chỗ đặt file,
|
|
34
|
+
tương thích public API, interface hay điểm đăng ký bắt buộc. Quy ước mềm: cách đặt tên,
|
|
35
|
+
hình dạng thư mục, phong cách test. Dẫn nguồn của từng quy tắc.
|
|
36
|
+
4. Tìm boilerplate hoặc template (ví dụ `templates/features/`) và feature đang có giống
|
|
37
|
+
nhất. Lặp lại cấu trúc, cách nối dây và test của nó.
|
|
38
|
+
5. Vẽ ra các module bị chạm và hướng của từng phụ thuộc mới. Một cạnh mới phải chỉ cùng
|
|
39
|
+
hướng với các cạnh cùng loại đang có.
|
|
40
|
+
6. Viết một bản thiết kế feature ngắn: file sẽ thêm hoặc sửa, module sở hữu, bề mặt public,
|
|
41
|
+
test. Đặt nó vào brief của lead/peer hoặc vào note của task.
|
|
42
|
+
7. Hiện thực theo các quy ước đang có. Ở trong các đường dẫn sở hữu.
|
|
43
|
+
8. Chạy các phép kiểm kiến trúc. Dùng công cụ lint và kiểm ranh giới của chính project
|
|
44
|
+
trước. Nếu project đã nhận file contract của ALP, hãy chạy thêm
|
|
45
|
+
`node <this skill dir>/scripts/check-boundaries.mjs --root <repo>`; mặc định nó đọc
|
|
46
|
+
`docs/architecture/contract.json` và thoát với mã 1 khi có vi phạm. Xem
|
|
47
|
+
[scripts/check-boundaries.mjs](scripts/check-boundaries.mjs).
|
|
48
|
+
9. Review diff đối chiếu với bản thiết kế. Chỉ cập nhật tài liệu kiến trúc hoặc contract
|
|
49
|
+
nếu một ranh giới hay contract thật sự đã đổi.
|
|
50
|
+
|
|
51
|
+
Một architect hoặc reviewer chỉ đọc chạy bước 1-6 và 8 trên bản đề xuất hoặc trên cây hiện
|
|
52
|
+
tại, rồi báo phát hiện và một bản thiết kế được khuyến nghị, thay vì sửa file.
|
|
53
|
+
|
|
54
|
+
## Ràng buộc
|
|
55
|
+
|
|
56
|
+
- Đừng bao giờ áp đặt Clean Architecture, DDD, Hexagonal, hay bất kỳ framework hoặc mẫu nào
|
|
57
|
+
mà project chưa dùng.
|
|
58
|
+
- Đừng thêm một abstraction, lớp hay interface chỉ để thoả một mẫu chung chung.
|
|
59
|
+
- Nếu kiến trúc không thể thoả yêu cầu, hãy dừng. Nêu rõ xung đột, cái được cái mất, và các
|
|
60
|
+
phương án, rồi chuyển quyết định lên trên
|
|
61
|
+
(peer -> lead -> main -> người dùng).
|
|
62
|
+
- Một ngoại lệ với quy tắc cứng cần một quyết định được ghi lại rõ ràng (một ADR hoặc một
|
|
63
|
+
note trong task nêu tên người đã duyệt). Đừng bao giờ lách một quy tắc trong im lặng, và
|
|
64
|
+
đừng sửa contract hay config lint để một vi phạm lọt qua.
|
|
65
|
+
- Các agent chỉ đọc (architect, reviewer) báo phát hiện; họ không sửa file.
|
|
66
|
+
- Skill này không cấp quyền cài công cụ, mở rộng phạm vi, hay ghi ra ngoài các đường dẫn
|
|
67
|
+
sở hữu.
|
|
68
|
+
|
|
69
|
+
## Kiểm chứng
|
|
70
|
+
|
|
71
|
+
- Lint, type check, test và công cụ kiểm ranh giới của project đều pass trên cây cuối cùng.
|
|
72
|
+
- `check-boundaries.mjs` thoát với mã 0 khi project dùng file contract.
|
|
73
|
+
- Mọi cạnh phụ thuộc mới khớp với hướng đã vẽ ở bước 5.
|
|
74
|
+
- Handoff: câu lệnh kiểm kèm output, các file đã đổi nhóm theo module, và mọi ngoại lệ đã
|
|
75
|
+
được duyệt kèm nơi ghi nó và người duyệt.
|
|
76
|
+
|
|
77
|
+
## Xử lý khi thất bại
|
|
78
|
+
|
|
79
|
+
- Vi phạm ranh giới: di chuyển code hoặc đảo hướng phụ thuộc theo cách feature tương tự đã
|
|
80
|
+
làm; chạy lại bộ kiểm. Đừng làm yếu quy tắc.
|
|
81
|
+
- Không có feature hay template tương tự: hãy nói thẳng, đề xuất phương án gần nhất, và hỏi
|
|
82
|
+
agent giao việc trước khi tự dựng một cấu trúc mới.
|
|
83
|
+
- Tài liệu và code xung đột: theo code mà các phép kiểm thực thi, ghi lại chỗ lệch, và báo lên.
|
|
84
|
+
- Bộ kiểm thiếu hoặc chạy không được: báo đúng câu lệnh và lỗi; đừng tuyên bố là đã kiểm
|
|
85
|
+
chứng được các ranh giới.
|
|
86
|
+
|
|
87
|
+
## Tài liệu tham chiếu
|
|
88
|
+
|
|
89
|
+
- [references/feature-design.md](references/feature-design.md) — đọc khi viết bản thiết kế feature (bước 6), khi chọn feature tương tự (bước 4), hoặc khi kiểm hướng phụ thuộc (bước 5).
|
|
90
|
+
- [references/architecture-contract.md](references/architecture-contract.md) — đọc khi project đã có hoặc muốn có một contract kiến trúc máy kiểm được.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Contract kiến trúc
|
|
2
|
+
|
|
3
|
+
Đọc khi project đã có `docs/architecture/contract.json`, hoặc muốn có các quy tắc phụ thuộc
|
|
4
|
+
mà một công cụ kiểm thay vì để reviewer phải nhớ.
|
|
5
|
+
|
|
6
|
+
## Ưu tiên công cụ của chính project
|
|
7
|
+
|
|
8
|
+
Nếu project đã thực thi ranh giới sẵn (một quy tắc boundaries hay import của ESLint,
|
|
9
|
+
dependency-cruiser, Nx module boundaries, import-linter cho Python, ArchUnit cho Java,
|
|
10
|
+
hay một script riêng như `scripts/check-boundaries.mjs` của chính nó), hãy dùng nó và
|
|
11
|
+
dừng ở đây. Contract dưới đây là phương án dự phòng cho các repository JavaScript/TypeScript
|
|
12
|
+
chưa có gì. Việc nhận nó là quyết định của project: hãy đề xuất, đừng tự thêm vào.
|
|
13
|
+
|
|
14
|
+
## Định dạng
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"description": "Layers of the orders service",
|
|
19
|
+
"modules": {
|
|
20
|
+
"api": ["src/api/**"],
|
|
21
|
+
"app": ["src/app/**"],
|
|
22
|
+
"domain": ["src/domain/**"],
|
|
23
|
+
"shared": ["src/shared/**"]
|
|
24
|
+
},
|
|
25
|
+
"allow": {
|
|
26
|
+
"api": ["app", "shared"],
|
|
27
|
+
"app": ["domain", "shared"],
|
|
28
|
+
"domain": ["shared"],
|
|
29
|
+
"shared": []
|
|
30
|
+
},
|
|
31
|
+
"denyPackages": { "domain": ["express", "pg", "node:fs"] },
|
|
32
|
+
"ignore": ["**/*.test.ts", "**/__fixtures__/**"],
|
|
33
|
+
"exceptions": [
|
|
34
|
+
{ "file": "src/domain/legacy-report.ts", "import": "src/api/**",
|
|
35
|
+
"reason": "Report export predates the layering; removed by #412", "approvedBy": "main, 2026-11-05",
|
|
36
|
+
"expires": "2027-03-31" }
|
|
37
|
+
]
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `modules`: tên -> các glob trên đường dẫn POSIX tương đối với repository (`**`, `*`, `?`).
|
|
42
|
+
Một file thuộc module đầu tiên có glob khớp; file không thuộc module nào thì không bị kiểm.
|
|
43
|
+
- `allow`: một module được liệt kê chỉ được import chính nó và các module được nêu tên. Module
|
|
44
|
+
không có trong `allow` thì không bị hạn chế, nên hãy liệt kê mọi module bạn muốn ràng buộc.
|
|
45
|
+
- `denyPackages`: tên package trần (hoặc builtin `node:`) mà một module không được import.
|
|
46
|
+
- `ignore`: các file không bao giờ bị kiểm.
|
|
47
|
+
- `exceptions`: bản ghi của việc chuyển lên. Mỗi mục cần `file` (một file, không dùng pattern),
|
|
48
|
+
`import` (một glob trên file bị import, hoặc một tên package; đừng bao giờ dùng `**`),
|
|
49
|
+
`reason` và `approvedBy`, và có thể có `expires` (YYYY-MM-DD; sau ngày đó nó không miễn gì
|
|
50
|
+
nữa). Chỉ thêm một mục sau khi quyết định đã được người sở hữu quy tắc đó đưa ra, đừng bao
|
|
51
|
+
giờ thêm để tự mình làm một phép kiểm đang fail lọt qua. Bộ kiểm sẽ liệt kê các exception
|
|
52
|
+
không ai cần.
|
|
53
|
+
|
|
54
|
+
## Thay đổi contract thì phải được review
|
|
55
|
+
|
|
56
|
+
Làm yếu contract (thêm một exception, nới `allow`, bỏ một package bị cấm, thêm một `ignore`,
|
|
57
|
+
đổi một module) sẽ làm mọi phép kiểm pass, nên đó là một quyết định giống như một exception.
|
|
58
|
+
Với `--base <git-ref>`, bộ kiểm so contract với bản ở ref đó và fail (thoát mã 1) với mọi chỗ
|
|
59
|
+
nới lỏng nó tìm thấy, nêu tên từng chỗ, cho tới khi lần chạy nói ra ai đã review
|
|
60
|
+
nó: `--approved-by "main, 2026-11-05"`. Siết chặt thì không cần review. Các gate chạy với
|
|
61
|
+
`--base` (`main` cho nhánh của một việc được giao, `origin/main` trong CI) và không bao giờ với
|
|
62
|
+
`--approved-by`; reviewer chạy cờ đó sau khi đã quyết.
|
|
63
|
+
|
|
64
|
+
## Bộ kiểm thấy những gì
|
|
65
|
+
|
|
66
|
+
`node <skill dir>/scripts/check-boundaries.mjs --root <repo> [--contract FILE] [--base REF [--approved-by NAME]] [--json]`
|
|
67
|
+
|
|
68
|
+
- Đọc `import ... from`, `export ... from`, `import '...'` dạng side-effect, `import('...')`
|
|
69
|
+
động và `require('...')`, bỏ qua comment, trong các file `.js .jsx .mjs .cjs .ts
|
|
70
|
+
.tsx .mts .cts` (bỏ qua `.d.ts`, `node_modules`, `dist`, `build`, `coverage`).
|
|
71
|
+
- Phân giải các specifier tương đối theo cách Node và TypeScript làm (phần mở rộng, `index.*`,
|
|
72
|
+
`./x.js` cho `./x.ts`). Alias đường dẫn (`@/x`, `paths` trong tsconfig) và specifier được
|
|
73
|
+
tính ra lúc chạy thì không được phân giải: project dùng alias cần công cụ riêng của nó.
|
|
74
|
+
- Thoát mã 0 là sạch, 1 là có vi phạm (`file:line from -> to (specifier): rule`) hoặc có một
|
|
75
|
+
chỗ nới lỏng chưa được review, 2 là contract, tham số hay base không hợp lệ. Nó chỉ đọc file
|
|
76
|
+
(và `git show <base>:<contract>`).
|
|
77
|
+
|
|
78
|
+
## Thực thi nó
|
|
79
|
+
|
|
80
|
+
Chỉ những quy tắc bộ kiểm xác minh được một cách đáng tin mới thuộc về một gate cứng.
|
|
81
|
+
|
|
82
|
+
- CI: thêm câu lệnh vào CI hoặc script test của project, với script được sao vào chính
|
|
83
|
+
repository (ví dụ `tools/check-boundaries.mjs`) để CI không cần thư viện ALP.
|
|
84
|
+
- ALP: một hook dạng blocking sẽ chặn một handoff, một lần đóng task hay một lần merge khi phép
|
|
85
|
+
kiểm còn fail; phần cuối output của nó là lý do agent đọc được. Một hook áp dụng cho các
|
|
86
|
+
agent nêu tên nó, nên người dùng (không phải agent) định nghĩa hook và cấp cho họ:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
alp hook add architecture --project --event handoff --command "node tools/check-boundaries.mjs --base main" --blocking --timeout 120
|
|
90
|
+
alp agent edit peer --project --hooks architecture
|
|
91
|
+
alp hook test architecture --project
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Dùng `--event task.close` (trên main hoặc lead) hay `--event merge` cho các gate còn lại.
|
|
95
|
+
Hook của project chỉ chạy khi người dùng đã tin workspace (`alp trust`).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Thiết kế feature
|
|
2
|
+
|
|
3
|
+
Đọc khi viết bản thiết kế feature, khi chọn feature tương tự, hoặc khi kiểm hướng của phụ thuộc mới.
|
|
4
|
+
|
|
5
|
+
## Chọn feature tương tự
|
|
6
|
+
|
|
7
|
+
Xếp hạng các ứng viên theo số điểm sau mà chúng chia sẻ với feature mới:
|
|
8
|
+
|
|
9
|
+
1. Cùng loại entry point (route HTTP, câu lệnh CLI, job, màn hình UI, event handler).
|
|
10
|
+
2. Cùng module hay lớp sở hữu, và cùng tập module mà nó phụ thuộc vào.
|
|
11
|
+
3. Cùng hình dạng lưu trữ hay tích hợp (đọc/ghi cùng một store hay service).
|
|
12
|
+
4. Mới được viết hoặc mới bị chạm tới, nên nó phản ánh quy ước hiện hành.
|
|
13
|
+
5. Có test theo phong cách project mong đợi.
|
|
14
|
+
|
|
15
|
+
Ưu tiên boilerplate hay generator của project khi có; dùng feature tương tự để bù phần
|
|
16
|
+
template bỏ sót. Nếu hai ứng viên mâu thuẫn nhau, hãy theo cái mà tài liệu kiến trúc hoặc
|
|
17
|
+
các phép kiểm hậu thuẫn, và ghi lại cái kia như một chỗ lệch.
|
|
18
|
+
|
|
19
|
+
Ghi lại lựa chọn đó trong bản thiết kế: "Mirrors `<path>` because <shared traits>."
|
|
20
|
+
|
|
21
|
+
## Mẫu thiết kế
|
|
22
|
+
|
|
23
|
+
Giữ nó vừa đủ cho những gì một reviewer cần để kiểm implementation. Bỏ các mục trống.
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
Feature: <one-line purpose>
|
|
27
|
+
Owning module: <module/package/layer>
|
|
28
|
+
Mirrors: <path of analogous feature or template> because <traits>
|
|
29
|
+
|
|
30
|
+
Hard constraints applied:
|
|
31
|
+
- <rule> (source: <doc/ADR/lint config>)
|
|
32
|
+
|
|
33
|
+
Files:
|
|
34
|
+
- add <path> <role in the feature>
|
|
35
|
+
- change <path> <what changes and why>
|
|
36
|
+
|
|
37
|
+
Public surface:
|
|
38
|
+
- <exported symbol / route / CLI flag / config key / event> new | changed
|
|
39
|
+
- Compatibility: <none affected | what callers must change>
|
|
40
|
+
|
|
41
|
+
Dependencies (from -> to):
|
|
42
|
+
- <module A> -> <module B> <existing edge kind it matches>
|
|
43
|
+
|
|
44
|
+
Tests:
|
|
45
|
+
- <test file> <behavior covered>
|
|
46
|
+
|
|
47
|
+
Open decisions / exceptions:
|
|
48
|
+
- <question or rule exception, who must decide>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Danh sách kiểm hướng phụ thuộc
|
|
52
|
+
|
|
53
|
+
Trả lời từng câu cho mỗi import, lời gọi hay lần đăng ký mới:
|
|
54
|
+
|
|
55
|
+
- Đã có một cạnh cùng loại chỉ theo hướng này chưa? Dẫn ra một cạnh.
|
|
56
|
+
- Cạnh đó có vượt một ranh giới lớp hay package mà tài liệu hoặc contract hạn chế không?
|
|
57
|
+
- Nó có tạo ra một vòng lặp giữa các module không? Kiểm cả hai hướng.
|
|
58
|
+
- Một module thấp hơn hoặc dùng chung bây giờ có import từ một module feature hay app không?
|
|
59
|
+
- Code domain hay core bây giờ có import một chi tiết framework, transport hay lưu trữ mà
|
|
60
|
+
feature tương tự vẫn giữ ở ngoài không?
|
|
61
|
+
- Một dependency chỉ dùng cho test hay chỉ dùng khi dev có thể chạm tới được từ code production
|
|
62
|
+
không?
|
|
63
|
+
- Feature có thò vào phần nội bộ của module khác thay vì vào entry point public của nó không?
|
|
64
|
+
- Một lần đăng ký mới (router, danh sách plugin, DI container, manifest) có được đặt đúng chỗ
|
|
65
|
+
mà feature tương tự đăng ký không?
|
|
66
|
+
|
|
67
|
+
Bất kỳ câu "có" nào về một lần vượt ranh giới bị hạn chế, một vòng lặp, hay một lần truy cập
|
|
68
|
+
phần nội bộ đều là vấn đề ràng buộc cứng: hãy sửa chỗ đặt, hoặc chuyển một quyết định ngoại lệ
|
|
69
|
+
lên trên trước khi hiện thực.
|