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.tspreferences-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 đó:

FilePhạm viMô tả
~/.gsd/PREFERENCES.mdToàn cụcCài đặt hành vi agent cho tất cả dự án
~/.gsd/agent/models.jsonToàn cụcĐăng ký LLM provider và model tùy chỉnh
~/.gsd/agent/KNOWLEDGE.mdToàn cụcQuy tắc thường trú được tiêm vào system prompt mỗi phiên
.gsd/KNOWLEDGE.mdDự ánQuy tắc riêng cho dự án - ghi đè / bổ sung thêm vào quy tắc toàn cục
Không có PREFERENCES.md cục bộ
PREFERENCES.md chỉ tồn tại ở cấp 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

~/.gsd/agent/models.json 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:

~/.gsd/agent/models.json json
{
  "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ể:

.gsd/PREFERENCES.md yaml
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 tasks
Kiểu API được hỗ trợ
GSD-2 hỗ trợ hai kiểu API: anthropic-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:

.gsd/PREFERENCES.md yaml
---
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."
---
Schema đầy đủ trong source
Toàn bộ interface GSD2Preferences được định nghĩa trong 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ố timeoutScale nộ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.

.gsd/PREFERENCES.md yaml
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ạp

Token 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 modelsphases ở lớp ưu tiên thấp nhất - giá trị người dùng đặt tường minh luôn thắng.

ProfileKhi dùngTradeoff
budgetTự độ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
balancedPhần lớn dự án; mặc định khi không cấu hìnhBỏ qua research và reassess; Sonnet-class cho subagent
qualityYêu cầu chất lượng cao, không cần toàn bộ phaseBỏ 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"
.gsd/PREFERENCES.md yaml
# 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_routing
Cài đặt tường minh luôn thắng
Token profile chỉ tác động đến các trường chưa được người dùng cấu hình tường minh. Nếu bạn đã đặt models.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.

~/.gsd/PREFERENCES.md yaml
---
# 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ơn
  • token_profile: balanced - cân bằng chi phí và chất lượng
  • auto_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.

~/.gsd/PREFERENCES.md yaml
---
# 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ánh
  • remote_questions - gửi câu hỏi leo thang lên Telegram và chờ trả lời
  • git.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.

~/.gsd/PREFERENCES.md yaml
---
# 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.

~/.gsd/agent/KNOWLEDGE.md markdown
# 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
KNOWLEDGE.md không được kiểm tra schema
KNOWLEDGE.md là văn bản thủ công và không qua bất kỳ quá trình xác thực nào. GSD-2 đọc nguyên file và tiêm vào context - điều này có nghĩa là lỗi ngữ pháp, hướng dẫn mâu thuẫn, hoặc nội dung quá dài đều sẽ ảnh hưởng trực tiếp đến hành vi của agent. Giữ file ngắn gọn, có tiêu mục ##, 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.

~/.gsd/PREFERENCES.md yaml
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 off không có dấu nháy thành boolean false. Loader tự coerce về string "off" nên cả hai cách viết đều hoạt động.
Override thủ công vẫn ưu tiên
Nếu trước khi chạy auto-mode bạn dù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.

~/.gsd/PREFERENCES.md yaml
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 $PATH và OpenAI API key đã cấu hình cho Codex. Thiếu binary codex, 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 (high3).
  • 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: true không sửa source - thay vào đó gọi gsd_slice_replan với findings làm rationale, sinh ra REPLAN.md mới cho slice.
Cross-model peer review, không phải self-review
Giá trị thực sự của 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 đã đủ.
worktree-merge: auto_fix mặc định tắt
Đây là gate cuối trước khi merge - mặc định 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.

Thay đổi có hiệu lực ở lần chạy tiếp theo
Mọi thay đổi trong PREFERENCES.md chỉ được áp dụng khi GSD-2 được khởi động lại. Nếu auto-mode đang chạy, thay đổi sẽ không có hiệu lực ngay lập tức - bạn cần /gsd stop và chạy lại /gsd auto để cấu hình mới được nạp.