Quyết định thiết kế & giả định cần xác minh¶
Ghi lại quyết định quan trọng và giả định, để người dùng biết chỗ cần chỉnh khi áp dụng vào dự án thật.
Đã xác minh từ môi trường (Phase 0)¶
Định dạng ZCode đọc từ tài liệu thật (zcode-configuration-guide, diagnosing-*) và file agent mẫu:
| Tài nguyên | Vị trí workspace | Định dạng |
|---|---|---|
| Agent (subagent) | .zcode/agents/<name>.md |
frontmatter: name, description, color, model, thoughtLevel, tools |
| Skill | .zcode/skills/<name>/SKILL.md |
frontmatter: name, description, when_to_use, license, metadata |
| Command | .zcode/commands/<name>.md |
tên = tên file; frontmatter: description, argument-hint, allowed-tools, model, skills, disable-noninteractive |
| Hook | .zcode/config.json → hooks |
{ enabled: true, events: { <Event>: [...] } }; 7 event hỗ trợ |
| Instructions | <repo>/AGENTS.md |
markdown, load vào context |
Quyết định thiết kế¶
- Board = GitHub Projects V2 (kanban), không dùng GitHub. Lý do: người dùng muốn quản lý bằng
GitHub; Projects V2 cho cột kéo-thả thật. Đánh đổi: API là GraphQL (
projectV2), phức tạp hơn REST. - Phân tách Status vs label. Status (todo/in-progress/review/done/deployed) là field single-select
của ProjectV2 (cột kanban);
role::*,claimed::*,needs-human,blockedlà label trên issue. - Vẫn giữ token
status::*làm tên option của field để toàn bộ docs/skills/rules không phải đổi. status::deployedlà field option, áp dụng được trên issue đã đóng. GitHub tự đóng issue khi PR merge (quaCloses #id); set field trên ProjectV2 item không phụ thuộc trạng thái issue.- GraphQL cho Projects V2, REST cho labels/comments (github.py gói cả hai).
- CI/CD = GitHub Actions (
.github/workflows/ci.yml). Duyệt production qua Environments → Required reviewers (thay chowhen: manualcủa GitHub). - Webhook xác thực HMAC-SHA256 (
X-Hub-Signature-256), khác cơ chế token header của GitHub. - Contract-first + OpenAPI. FE/BE dùng chung
specs/api-contract.yaml, code song song. - Chỉ 2 điểm human approve: duyệt design và duyệt deploy prod.
- Truyền artifact qua
handoffs/<issue-id>/thay vì chat tự do. - Agent definition theo frontmatter ZCode để orchestrator spawn đúng subagent.
Giả định / chỗ cần xác minh khi dùng thật¶
- Trường
modeltrong.zcode/agents/*.mdlà placeholder (Opus/Sonnet). Phải thay bằng model id thực đã cấu hình trong ZCode (ListModels/ Settings → Subagents). thoughtLevelchỉ thấy giá trịmaxtrong file mẫu; template dùngmaxcho orchestrator/ designer, bỏ qua cho phần còn lại. Cần xác minh các giá trị khác nếu muốn tinh chỉnh.- ProjectV2 cần cấu hình tay một lần: tạo field
Statusvới đúng 5 optionstatus::*(README mục 2). Scriptgithub.pytìm field/option theo tên nên không phụ thuộc ID cứng — nhưng nếu đổi tên option thì phải đồng bộconfig/board.yml. - ProjectV2 ở cấp repo (
repository.projectsV2). Nếu dùng project cấp organization, cần mở rộnggithub.pysangorganization.projectsV2. - Hook pre-write-guard / secret-scan là mẫu tham chiếu: hook
PreToolUsechỉ nhận tool name qua matcher, cần nối biếnZCODE_AGENTvào runtime để chặn ghi sai path chính xác. - Webhook receiver chỉ là mẫu; cần deploy nơi GitHub gọi tới được và đặt
GITHUB_WEBHOOK_SECRET. - Stack-agnostic:
config/stack.ymlcung cấp preset mặc định (Node/TypeScript FE + BE) — thay bằng stack thật của dự án. - Board token cần PAT:
GITHUB_TOKENmặc định của Actions không truy cập Projects V2, nên jobboard-sync-deployeddùngsecrets.GH_TOKEN.