Bỏ qua

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ế

  1. 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.
  2. 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, blocked là label trên issue.
  3. Vẫn giữ token status::* làm tên option của field để toàn bộ docs/skills/rules không phải đổi.
  4. status::deployed là field option, áp dụng được trên issue đã đóng. GitHub tự đóng issue khi PR merge (qua Closes #id); set field trên ProjectV2 item không phụ thuộc trạng thái issue.
  5. GraphQL cho Projects V2, REST cho labels/comments (github.py gói cả hai).
  6. CI/CD = GitHub Actions (.github/workflows/ci.yml). Duyệt production qua Environments → Required reviewers (thay cho when: manual của GitHub).
  7. Webhook xác thực HMAC-SHA256 (X-Hub-Signature-256), khác cơ chế token header của GitHub.
  8. Contract-first + OpenAPI. FE/BE dùng chung specs/api-contract.yaml, code song song.
  9. Chỉ 2 điểm human approve: duyệt design và duyệt deploy prod.
  10. Truyền artifact qua handoffs/<issue-id>/ thay vì chat tự do.
  11. Agent definition theo frontmatter ZCode để orchestrator spawn đúng subagent.

Giả định / chỗ cần xác minh khi dùng thật

  1. Trường model trong .zcode/agents/*.md là placeholder (Opus/Sonnet). Phải thay bằng model id thực đã cấu hình trong ZCode (ListModels / Settings → Subagents).
  2. thoughtLevel chỉ thấy giá trị max trong file mẫu; template dùng max cho 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.
  3. ProjectV2 cần cấu hình tay một lần: tạo field Status với đúng 5 option status::* (README mục 2). Script github.py tì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.
  4. ProjectV2 ở cấp repo (repository.projectsV2). Nếu dùng project cấp organization, cần mở rộng github.py sang organization.projectsV2.
  5. Hook pre-write-guard / secret-scan là mẫu tham chiếu: hook PreToolUse chỉ nhận tool name qua matcher, cần nối biến ZCODE_AGENT vào runtime để chặn ghi sai path chính xác.
  6. Webhook receiver chỉ là mẫu; cần deploy nơi GitHub gọi tới được và đặt GITHUB_WEBHOOK_SECRET.
  7. Stack-agnostic: config/stack.yml cung cấp preset mặc định (Node/TypeScript FE + BE) — thay bằng stack thật của dự án.
  8. Board token cần PAT: GITHUB_TOKEN mặc định của Actions không truy cập Projects V2, nên job board-sync-deployed dùng secrets.GH_TOKEN.