Xây repo (kho mã nguồn) để Codex có thể hiểu, chỉnh sửa và kiểm chứng.
Một project template (mẫu dự án) thực dụng cho Codex và coding agents (agent lập trình): hướng dẫn rõ ràng, design docs (tài liệu thiết kế), executable scripts (script có thể chạy), CI gates (cổng kiểm tra tự động), security rules (quy tắc bảo mật), prompt libraries (thư viện prompt), và repeatable workflows (quy trình lặp lại được).
repo/ ├── AGENTS.md ├── README.md ├── docs/design.md ├── docs/architecture/ ├── examples/ ├── scripts/ │ ├── bootstrap.sh │ ├── lint.sh │ ├── test.sh │ ├── build.sh │ └── verify.sh ├── tests/ ├── .agents/skills/ ├── .github/codex/prompts/ └── .github/workflows/ci.yml
Repository blueprint (khung thiết kế repo)
Repository (kho mã nguồn) nên là source of truth (nguồn thông tin chuẩn). Codex làm việc tốt nhất khi nó có thể nhanh chóng tìm thấy project contract (quy ước vận hành của dự án), hiểu thiết kế, chạy deterministic checks (kiểm tra nhất quán/tất định), và tạo reviewable diffs (các thay đổi mã nguồn dễ đánh giá/review).
1. Instructions (hướng dẫn)
Dùng một file AGENTS.md ngắn gọn ở root (thư mục gốc). Đặt operational rules (quy tắc vận hành) ở đó, không biến nó thành bài luận kiến trúc dài.
2. Design context (bối cảnh thiết kế)
Đặt system intent (ý định thiết kế hệ thống), tradeoffs (đánh đổi), interfaces (giao diện/kết nối), và rollout notes (ghi chú triển khai) trong docs/design.md.
3. Verification (kiểm chứng)
Cung cấp one-command scripts (script chạy bằng một lệnh) cho bootstrap (khởi tạo môi trường), lint (kiểm tra style/lỗi tĩnh), test (kiểm thử), build (đóng gói), và verify (xác minh tổng hợp).
| File / folder (tệp / thư mục) | Priority (mức ưu tiên) | Purpose (mục đích) |
|---|---|---|
AGENTS.md | Required (bắt buộc) | Quy tắc vận hành cho agent, commands (lệnh), constraints (ràng buộc), và done criteria (tiêu chí hoàn thành). |
README.md | Required (bắt buộc) | Overview (tổng quan) cho con người đọc, quickstart (bắt đầu nhanh), cách dùng, và repo map (bản đồ cấu trúc repo). |
docs/design.md | Recommended (khuyến nghị) | Architecture (kiến trúc), constraints (ràng buộc), data flows (luồng dữ liệu), security notes (ghi chú bảo mật), và rollout plan (kế hoạch triển khai). |
scripts/verify.sh | Required (bắt buộc) | Canonical pre-PR command (lệnh chuẩn trước khi mở PR) cho agent và con người. |
tests/ | Required (bắt buộc) | Coverage (độ phủ kiểm thử) cho unit (kiểm thử đơn vị), integration (kiểm thử tích hợp), smoke (kiểm thử nhanh), và regression (kiểm thử hồi quy/chống lỗi tái diễn). |
examples/ | Recommended (khuyến nghị) | Runnable examples (ví dụ chạy được) để định nghĩa expected behavior (hành vi kỳ vọng). |
.github/workflows/ci.yml | Required (bắt buộc) | Gate (cổng kiểm tra) tự động cho lint/test/build. |
.github/codex/prompts/ | Recommended (khuyến nghị) | Prompts (câu lệnh/hướng dẫn cho AI) tái sử dụng cho PR review (đánh giá/duyệt pull request), release (phát hành), migration (chuyển đổi/nâng cấp dữ liệu hoặc hệ thống), và bugfix (sửa lỗi). |
.agents/skills/ | Optional (tuỳ chọn) | Task-specific workflows (quy trình theo từng loại việc) có thể tái sử dụng cho công việc agent lặp lại. |
SECURITY.md | Required (bắt buộc) | Cách báo cáo vulnerability (lỗ hổng), supported versions (phiên bản được hỗ trợ), và security contact (liên hệ bảo mật). |
AGENTS.md nên ngắn gọn và operational (tập trung vận hành)
Hãy xem nó như contract (quy ước) về cách Codex nên làm việc trong repo. Phần architecture (kiến trúc) và product thinking (tư duy sản phẩm) dài nên chuyển sang docs (tài liệu).
- Đọc README và design docs (tài liệu thiết kế) trước
- Giữ changes (thay đổi) đúng scope (phạm vi)
- Thêm hoặc cập nhật tests (kiểm thử)
- Chạy canonical scripts (script chuẩn)
- Không bao giờ commit secrets (đưa khóa/bí mật vào mã nguồn)
- Tóm tắt risks (rủi ro) và validation (cách đã kiểm chứng)
# AGENTS.md ## Required workflow (quy trình bắt buộc) 1. Đọc README.md và docs/design.md. 2. Giữ changes (thay đổi) đúng scope (phạm vi) của task. 3. Thêm hoặc cập nhật tests (kiểm thử) khi có behavior changes (thay đổi hành vi). 4. Chạy: - ./scripts/lint.sh - ./scripts/test.sh - ./scripts/build.sh khi cần 5. Báo cáo changed files (các tệp thay đổi), validation (xác minh/kiểm chứng), và risks (rủi ro). ## Security rules (quy tắc bảo mật) - Không bao giờ commit secrets (đưa khóa/bí mật vào mã nguồn). - Không log credentials (thông tin đăng nhập) hoặc PII (dữ liệu định danh cá nhân). - Hỏi trước khi có network changes (thay đổi dùng mạng), destructive changes (thay đổi phá huỷ/xoá), hoặc permission changes (thay đổi quyền).
Codex workflow (quy trình làm việc với Codex) hiệu quả
Vòng lặp đáng tin cậy nhất là small task (task nhỏ) → design note (ghi chú thiết kế) → isolated branch/worktree (nhánh/worktree tách biệt) → implementation (triển khai) → verification (kiểm chứng) → AI + human review (đánh giá từ AI và con người).
CI gates (cổng kiểm tra tự động)
Dùng required status checks (kiểm tra bắt buộc) cho lint, tests, build, dependency review (đánh giá thư viện phụ thuộc), code scanning (quét mã), và secret scanning (quét khóa/bí mật). AI review hữu ích, nhưng không thay thế trách nhiệm của con người.
Security posture (trạng thái/mô hình bảo mật)
Mặc định read-only exploration (khảo sát chỉ đọc), workspace-write implementation (chỉ ghi trong workspace), limited network access (giới hạn truy cập mạng), không đưa secrets (khóa/bí mật) vào prompts (câu lệnh/chỉ dẫn cho AI), và cần approval (phê duyệt) cho destructive commands (lệnh phá huỷ/xoá).
Starter checklist (checklist khởi đầu)
- Thêm các file README, AGENTS, design, contributing, security, và license
- Tạo bootstrap, lint, test, build, và verify scripts (các script khởi tạo/kiểm tra/đóng gói/xác minh)
- Thêm runnable examples (ví dụ chạy được) và regression tests (kiểm thử chống lỗi tái diễn)
- Bảo vệ main (nhánh chính) bằng required checks (kiểm tra bắt buộc) và CODEOWNERS (chủ sở hữu mã)
- Thêm prompt files (file prompt) cho các Codex workflows (quy trình Codex) lặp lại
- Thêm skills (kỹ năng/quy trình xử lý của agent) cho các multi-step agent tasks (task agent nhiều bước) lặp lại
- Bật dependency review (đánh giá thư viện phụ thuộc), code scanning (quét mã), và secret scanning (quét khóa/bí mật)
- Dùng worktrees (bản làm việc tách riêng) cho các agent tasks (nhiệm vụ của agent) chạy song song hoặc rủi ro
Cloudflare Pages deploy (triển khai lên Cloudflare Pages)
Site này là static (tĩnh). Deploy (triển khai) folder này bằng Wrangler (CLI của Cloudflare) hoặc kéo-thả vào Cloudflare Pages.
# Từ folder này: npm create cloudflare@latest codex-project-playbook # hoặc deploy trực tiếp lên Pages: npx wrangler pages project create codex-project-playbook npx wrangler pages deploy . --project-name=codex-project-playbook