Cấu hình GSD-2
GSD-2 sử dụng ba file cấu hình toàn cục: ~/.gsd/PREFERENCES.md lưu cài đặt
hành vi của agent, ~/.gsd/agent/models.json đăng ký provider và model,
và ~/.gsd/agent/KNOWLEDGE.md giữ các quy tắc phản hồi thường trú. Để ghi
đè quy tắc cho một dự án cụ thể, thêm file .gsd/KNOWLEDGE.md vào thư mục
dự án. Tất cả các trường trong PREFERENCES.md đều tùy chọn - giá trị mặc định được lấy từ
source files preferences-types.ts và preferences-models.ts.
Nơi lưu trữ cấu hình
Tất cả file cấu hình toàn cục nằm trong thư mục home. Để ghi đè quy tắc cho một dự án cụ thể,
chỉ cần thêm .gsd/KNOWLEDGE.md vào thư mục gốc của dự án đó:
| File | Phạm vi | Mô tả |
|---|---|---|
| ~/.gsd/PREFERENCES.md | Toàn cục | Cài đặt hành vi agent cho tất cả dự án |
| ~/.gsd/agent/models.json | Toàn cục | Đăng ký LLM provider và model tùy chỉnh |
| ~/.gsd/agent/KNOWLEDGE.md | Toàn cục | Quy tắc thường trú được tiêm vào system prompt mỗi phiên |
| .gsd/KNOWLEDGE.md | Dự án | Quy tắc riêng cho dự án - ghi đè / bổ sung thêm vào quy tắc toàn cục |
~/.gsd/PREFERENCES.md). Để tùy
chỉnh hành vi cho riêng một dự án, dùng .gsd/KNOWLEDGE.md trong thư mục dự án
đó - đây là cách duy nhất để ghi đè quy tắc theo phạm vi dự án.Models và Providers
models.json cho phép đăng ký bất kỳ LLM provider nào có API tương thích Anthropic Messages. Sau khi
đăng ký, model được tham chiếu trong PREFERENCES.md theo định dạng <provider-id>/<model-id>.
Cấu trúc models.json
{
"providers": {
"<provider-id>": {
"baseUrl": "https://your-proxy.example.com",
"api": "anthropic-messages",
"apiKey": "sk-your-key-here",
"models": [
{
"id": "model-id-in-registry",
"name": "Human-readable name",
"contextWindow": 200000,
"maxTokens": 32768
}
]
}
}
}Ví dụ Claudible
Ví dụ thực tế sử dụng Claudible - một proxy đa provider hỗ trợ cả Claude lẫn GPT:
{
"providers": {
"claudible": {
"baseUrl": "https://claudible.io",
"api": "anthropic-messages",
"apiKey": "sk-your-key-here",
"models": [
{ "id": "claudible-claude-opus-4-7", "name": "Claude Opus 4.7", "contextWindow": 1000000, "maxTokens": 32768 },
{ "id": "claudible-claude-sonnet-4-6", "name": "Claude Sonnet 4.6", "contextWindow": 200000, "maxTokens": 32768 },
{ "id": "claudible-claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "contextWindow": 200000, "maxTokens": 32768 }
]
}
}
}Tham chiếu trong PREFERENCES.md
Sau khi provider được đăng ký, mỗi pipeline phase được gán vào một model cụ thể:
models:
research: claudible/claudible-claude-haiku-4-5-20251001 # phase: research-milestone
planning: claudible/claudible-claude-opus-4-7 # phase: plan-milestone
execution: claudible/claudible-claude-sonnet-4-6 # phase: execute-task
completion: claudible/claudible-claude-sonnet-4-6 # phase: complete-slice
subagent: claudible/claudible-claude-sonnet-4-6 # sub-agents spawned during tasksanthropic-messages cho các provider dùng Anthropic
Messages format, và openai-completions cho các provider tương thích OpenAI.
Kiểm tra tài liệu của provider cụ thể để xác định giá trị api phù hợp.Cấu trúc PREFERENCES.md
PREFERENCES.md là file Markdown có YAML frontmatter. Các trường được tổ chức thành 6 nhóm chính:
- Core - phiên bản schema, ngôn ngữ, hướng dẫn tùy chỉnh, skill discovery
- Models & Routing - gán model cho từng phase, cấu hình dynamic routing theo ngân sách
- Execution - lệnh xác minh, phản hồi lỗi, cô lập task qua worktree hoặc branch
- Verification - các phase có thể bật/tắt, độ sâu xác minh, enhanced_verification
- Git & Workflow - auto_push, chiến lược merge, tên nhánh chính, remote
- Advanced Context - budget ceiling, context_selection, token profile, safety harness
Ví dụ các trường trong nhóm Core:
---
version: 1
mode: auto
skill_discovery: suggest # "suggest" | "auto" | "off"
language: Vietnamese # ngôn ngữ phản hồi
custom_instructions:
- "Giao tiếp với người dùng bằng tiếng Việt có dấu."
- "All generated files (PLAN.md, ROADMAP.md, etc.) must be written in English."
- "Code comments and git commit messages must be in English."
---preferences-types.ts và giá trị mặc định trong preferences-models.ts. Các file này là nguồn chính xác nhất cho tất cả
các trường và kiểu dữ liệu.Thời gian giám sát (auto_supervisor)
Auto supervisor theo dõi tác nhân thực thi trong auto-mode và tạm dừng nếu task bị mắc kẹt hoặc vượt quá ngưỡng thời gian. Có ba mức ngưỡng:
- soft_timeout_minutes (mặc định: 20) - Cảnh báo khi task vượt quá ngưỡng này; auto-mode tiếp tục nhưng ghi nhận cảnh báo.
- idle_timeout_minutes (mặc định: 10) - Tạm dừng nếu không có tiến độ nào được ghi nhận trong khoảng này; không bao giờ được nhân với hệ số scale.
- hard_timeout_minutes (mặc định: 30) - Buộc tạm dừng sau khoảng thời gian tuyệt đối này. Giá trị này được nhân với hệ số
timeoutScalenội tại cho task phức tạp.
Tăng các giá trị này khi làm việc với task nghiên cứu lớn, refactor có nhiều file, hoặc build hệ thống phân tán mà tác nhân cần nhiều bước xác nhận.
auto_supervisor:
soft_timeout_minutes: 20 # Default: 20 -- Cảnh báo khi task vượt qua ngưỡng này
idle_timeout_minutes: 10 # Default: 10 -- Tạm dừng nếu không có tiến độ trong khoảng này
hard_timeout_minutes: 30 # Default: 30 -- Cấp tuyệt đối; tăng lên với task phức tạpToken profiles
token_profile là phím tắt để áp dụng bộ cấu hình model và phase có sẵn. Nó ghi đè cài đặt models và phases ở lớp ưu tiên thấp nhất - giá trị người dùng đặt tường minh luôn thắng.
| Profile | Khi dùng | Tradeoff |
|---|---|---|
| budget | Tự động hóa tối ưu chi phí, dự án nhỏ | Bỏ qua research, reassess, slice research, milestone validation; dùng Haiku-class cho execution |
| balanced | Phần lớn dự án; mặc định khi không cấu hình | Bỏ qua research và reassess; Sonnet-class cho subagent |
| quality | Yêu cầu chất lượng cao, không cần toàn bộ phase | Bỏ qua research và slice research; kế thừa cài đặt model của người dùng |
| burn-max | Ưu tiên chất lượng tối đa, không quan tâm chi phí | Bật tất cả phase; vô hiệu hóa dynamic_routing; context_selection chuyển sang "full" |
# Chọn một trong các giá trị: budget | balanced | quality | burn-max
token_profile: balanced
# Ví dụ thay thế:
# token_profile: burn-max # Bật tất cả phase, vô hiệu hóa dynamic_routingmodels.execution: claudible/claude-opus-4.7, giá trị đó được
giữ nguyên bất kể profile là gì.Preset cấu hình
Ba preset dưới đây là các điểm khởi đầu thực tế. Sao chép vào ~/.gsd/PREFERENCES.md hoặc .gsd/PREFERENCES.md rồi chỉnh sửa theo nhu cầu.
Preset A - Solo
Dành cho lập trình viên đơn lẻ làm việc trên một nhánh duy nhất với Claudible.
---
# Preset A: Solo developer (claudible, balanced, auto-commit)
version: 1
token_profile: balanced
models:
research: claudible/claudible-claude-haiku-4-5-20251001
planning: claudible/claudible-claude-opus-4-7
execution: claudible/claudible-claude-sonnet-4-6
completion: claudible/claudible-claude-sonnet-4-6
subagent: claudible/claudible-claude-sonnet-4-6
auto_supervisor:
soft_timeout_minutes: 20
idle_timeout_minutes: 10
hard_timeout_minutes: 30
verification_commands:
- npm run lint
- npm run test
git:
auto_push: false
merge_strategy: merge
main_branch: main
unique_milestone_ids: false
auto_report: true
skill_discovery: suggest
language: Vietnamese
---unique_milestone_ids: false- ID tuần tự đơn giản, dễ đọc hơntoken_profile: balanced- cân bằng chi phí và chất lượngauto_push: false- kiểm soát git thủ công trước khi push
Preset B - Team / Remote
Dành cho nhóm làm việc trên nhiều nhánh song song với khả năng gửi câu hỏi lên Telegram.
---
# Preset B: Team / Remote-questions (parallel branches, Telegram escalation)
version: 1
token_profile: balanced
unique_milestone_ids: true # Không bị xung đột khi chạy trên nhiều branch
models:
research: claudible/claudible-claude-haiku-4-5-20251001
planning: claudible/claudible-claude-opus-4-7
execution: claudible/claudible-claude-sonnet-4-6
completion: claudible/claudible-claude-sonnet-4-6
subagent: claudible/claudible-claude-sonnet-4-6
remote_questions:
channel: telegram
channel_id: "-5000550222"
timeout_minutes: 5
poll_interval_seconds: 5
auto_supervisor:
soft_timeout_minutes: 20
idle_timeout_minutes: 10
hard_timeout_minutes: 30
verification_commands:
- npm run lint
- npm run test
- npm run typecheck
git:
isolation: branch
auto_push: false
merge_strategy: squash
main_branch: main
remote: origin
phases:
mid_execution_escalation: true # Gửi câu hỏi lên Telegram khi cần thiết
skill_discovery: suggest
auto_report: true
language: Vietnamese
---unique_milestone_ids: true- tránh xung đột ID khi merge nhánhremote_questions- gửi câu hỏi leo thang lên Telegram và chờ trả lờigit.isolation: branch- mỗi task chạy trên nhánh riêng
Preset C - Burn-max
Dành cho những task đòi hỏi chất lượng cao nhất mà không quan tâm đến chi phí token.
---
# Preset C: Burn-max (tất cả phase, chất lượng cao nhất)
# Lưu ý: dynamic_routing tự động bị vô hiệu hóa, context_selection chuyển sang "full"
version: 1
token_profile: burn-max
models:
research: claudible/claudible-claude-opus-4-7
planning: claudible/claudible-claude-opus-4-7
execution: claudible/claudible-claude-opus-4-7
completion: claudible/claudible-claude-opus-4-7
subagent: claudible/claudible-claude-sonnet-4-6
auto_supervisor:
soft_timeout_minutes: 30 # Tăng lên vì task phức tạp hơn
idle_timeout_minutes: 15
hard_timeout_minutes: 60
verification_commands:
- npm run lint
- npm run test
- npm run build
git:
auto_push: false
merge_strategy: merge
main_branch: main
unique_milestone_ids: true
auto_report: true
skill_discovery: auto
language: Vietnamese
---- Tất cả model đều dùng Opus - chất lượng tối đa cho mọi phase
token_profile: burn-max- bật tất cả phase, vô hiệu hóa dynamic_routing- Supervisor timeout tăng lên (30/15/60 phút) vì task phức tạp hơn
Quy tắc thường trú với KNOWLEDGE.md
~/.gsd/agent/KNOWLEDGE.md là file Markdown thuần túy được tiêm vào system prompt của agent trong mỗi phiên. Phù hợp
với những quy tắc dài hơn có cấu trúc - chính sách ngôn ngữ, quy ước nhóm, ưu tiên công
cụ, các pattern cần được tuân thủ xuyên suốt mọi dự án.
Để thêm quy tắc riêng cho một dự án cụ thể, tạo file .gsd/KNOWLEDGE.md trong thư mục gốc của dự án. GSD-2 sẽ nạp cả hai file, với quy tắc cục bộ bổ sung vào
sau quy tắc toàn cục.
# Language Rules
## User Communication
- ALL user-facing communication MUST be in Vietnamese (tiếng Việt có dấu)
- This includes: interactive questions, discussion prompts, status updates,
progress reports, error messages, summaries, and any text displayed to the user
- Use proper Vietnamese diacritics at all times
## Written Artifacts
- ALL generated files MUST be written in English: PLAN.md, RESEARCH.md,
ROADMAP.md, PROJECT.md, REQUIREMENTS.md, and other planning artifacts
- Code comments and git commit messages MUST be in English
- PR titles and descriptions MUST be in English
# Web Search Preference
## Web Search & Fetch
- Always prefer Linkup MCP tools over native search-the-web / fetch_page
- Use linkup-search with depth: "deep" for complex research queries
- Use linkup-search with depth: "standard" for simple factual lookups
- Only fall back to native tools if Linkup MCP is unavailable or returns errors##, và kiểm tra lại định kỳ.Thinking Policy
thinking_policy cho phép tinh chỉnh mức độ reasoning theo từng unit type trong auto-mode. Đây là cách
tiết kiệm token cho các unit cơ học (như execute-task, complete-slice) và đồng thời nâng chất lượng cho các unit
quyết định nặng (như plan-milestone, replan-slice) - thay vì dùng một mức thinking duy nhất cho
cả phiên auto-mode.
thinking_policy:
# Safety net cho unit type không được map ở dưới.
# Mỗi unit type đã có rule riêng nên default hiếm khi được dùng.
default: medium
prefixes:
# Quyết định nặng — ảnh hưởng mọi thứ phía sau
plan-: high # plan-milestone, plan-slice
discuss-: high # discuss-milestone, discuss-slice
# Tổng hợp nhưng không reasoning sâu
research-: medium # research-milestone, research-slice
# Wrap-up cơ học — không cần thinking
complete-: "off" # complete-slice, complete-milestone
unitTypes:
# Execute thực hiện theo plan — thinking đã đầu tư ở phase plan.
# Nếu execute fail thì replan-slice sẽ chạy ở mức high.
execute-task: "off"
execute-task-simple: "off"
reactive-execute: "off"
# Quyết định blast-radius lớn — phải reasoning kỹ
replan-slice: high # chẩn đoán failure và đề xuất hướng mới
reassess-roadmap: high # re-shape toàn bộ roadmap giữa chừng
gate-evaluate: high # pass/fail gate chặn tiến độ
# Judgment, không cần deep design
refine-slice: medium # tinh chỉnh plan đã có
validate-milestone: medium
run-uat: medium
# Cơ học thuần túy
worktree-merge: "off"
# Sinh prose mạch lạc, reasoning nhẹ
rewrite-docs: low- Levels hợp lệ:
off,minimal,low,medium,high,xhigh. - Thứ tự resolve (match đầu tiên thắng):
unitTypes[unitType]→prefixes[longest matching]→default→ mức thinking lúc khởi động auto-mode. - Prefix nên kết thúc bằng
-(ví dụplan-); thiếu dấu gạch sẽ bị warning chứ không lỗi. - YAML diễn dịch
offkhông có dấu nháy thành booleanfalse. Loader tự coerce về string"off"nên cả hai cách viết đều hoạt động.
/thinking high để chỉnh tay, mức đó sẽ
thắng thinking_policy cho cả phiên. Policy chỉ áp dụng khi
không có override từ session hiện tại.Codex Peer Review
codex_review gắn OpenAI Codex CLI vào auto-loop dưới vai trò peer reviewer cross-model: ở các điểm complete-task, plan-slice,
hoặc worktree-merge, GSD-2 gửi diff hoặc plan tới Codex (model
thuộc dòng GPT) và xử lý findings nó trả về. Khi auto_fix: true,
subagent gsd-codex-fixer sẽ áp dụng các đề xuất, commit từng
finding một, rồi gọi reviewer chạy lại - lặp tối đa max_cycles lần trước khi bỏ cuộc.
Mỗi điểm trigger có thể bật/tắt và override độc lập. Toàn bộ tích hợp chạy trên hook engine
sẵn có (post_unit_hooks) - khối codex_review được expand thành các hook tổng hợp lúc load preferences.
codex_review:
enabled: true
codex_model: gpt-5.5 # Model của Codex CLI — đóng vai trò peer reviewer cross-model
default_reasoning_level: xhigh # low | medium | high | xhigh
default_max_cycles: 3 # số vòng review → fix → re-review tối đa
hooks:
# Auto peer-review sau mỗi task hoàn thành.
# Codex review diff của Claude; auto_fix dispatch gsd-codex-fixer áp dụng suggestion.
complete-task:
enabled: true
mode: blocking # halt auto-loop nếu còn findings
auto_fix: true
severity_threshold: low
# Plan review nặng và hiếm khi đổi outcome — default off.
# Bật enabled+advisory cho slice nào plan còn phân vân.
plan-slice:
enabled: false
mode: advisory
auto_fix: true # với plan-slice, "fix" = trigger gsd_slice_replan
# Pre-merge gate. auto_fix tắt — surface findings để user quyết định.
worktree-merge:
enabled: true
mode: blocking
auto_fix: false
severity_threshold: medium
reasoning_level: xhigh # critical gate, suy nghĩ kỹ nhất ở đây- Yêu cầu runtime: OpenAI Codex CLI cài trên
$PATHvà OpenAI API key đã cấu hình cho Codex. Thiếu binarycodex, reviewer sẽ ghi artifact lỗi và auto-loop vẫn chạy bình thường. - Trigger:
complete-task(sau khi task pass verification),plan-slice(sau khi slice plan ghi xong),worktree-merge(trước khi merge worktree về main). - Mode:
blocking- halt auto-loop nếu sau tất cả vòng vẫn còn findings;advisory- chỉ log vào journal rồi tiếp tục. - Severity threshold: findings có mức thấp hơn ngưỡng được lọc bỏ trước
khi quyết định PASS/FIX. Ngưỡng hợp lệ:
low,medium,high,critical. - Resolution của
reasoning_level/max_cycles(match đầu tiên thắng): per-hook override →default_reasoning_level/default_max_cycles→ fallback nội tại (highvà3). - Verdict artifact lưu tại
.gsd/codex-review/<trigger>.json(theo unit). Khi artifact đã có, hook engine bỏ qua re-fire - đảm bảo idempotency. - Với
plan-slice,auto_fix: truekhông sửa source - thay vào đó gọigsd_slice_replanvới findings làm rationale, sinh raREPLAN.mdmới cho slice.
codex_review là review chéo giữa hai
model family (Claude review code do Claude viết có chung blind spot; Codex/GPT review cùng
diff thường catch được những lỗi mà Claude bỏ qua, và ngược lại). Nếu chỉ cần self-review
thủ công, lệnh native /gsd-code-review đã đủ.auto_fix: false để findings được surface ra cho bạn quyết định, thay vì auto-edit vào commit sắp merge.
Bật auto_fix: true khi đã trust hoàn toàn fixer
(và đảm bảo verification_commands đủ chặt).Áp dụng thay đổi
Các thay đổi trong PREFERENCES.md, KNOWLEDGE.md, và models.json đều được đọc khi GSD-2 khởi động. Nếu auto-mode đang chạy, bạn cần dừng và khởi động lại để cấu hình mới có hiệu lực.
/gsd stop và chạy lại /gsd auto để cấu hình mới được nạp.