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

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",
      "headers": {
        "User-Agent": "claude-code/2.1.100 (external, sdk-cli)"
      },
      "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",
      "headers": {
        "User-Agent": "claude-code/2.1.100 (external, sdk-cli)"
      },
      "models": [
        { "id": "claude-opus-4.7",   "name": "Claude Opus 4.7",   "contextWindow": 200000, "maxTokens": 32768 },
        { "id": "claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "contextWindow": 200000, "maxTokens": 32768 },
        { "id": "claude-haiku-4.5",  "name": "Claude Haiku 4.5",  "contextWindow": 200000, "maxTokens": 32768 },
        { "id": "gpt-5.4",           "name": "GPT 5.4",           "contextWindow": 200000, "maxTokens": 32768 },
        { "id": "gpt-5.4-mini",      "name": "GPT 5.4 Mini",      "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/claude-haiku-4.5   # phase: research-milestone
  planning:         claudible/claude-opus-4.7    # phase: plan-milestone
  execution:        claudible/claude-sonnet-4.6  # phase: execute-task
  completion:       claudible/gpt-5.4            # phase: complete-slice
  subagent:         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             # ngon ngu phan hoi
custom_instructions:
  - "Giao tiep voi nguoi dung bang tieng Viet co dau."
  - "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  -- Canh bao khi task vuot qua nguong nay
  idle_timeout_minutes: 10   # Default: 10  -- Tam dung neu khong co tien do trong khoang nay
  hard_timeout_minutes: 30   # Default: 30  -- Cap tuyet doi; tang len voi task phuc tap

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 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"

.gsd/PREFERENCES.md yaml

# Chon mot trong cac gia tri: budget | balanced | quality | burn-max
token_profile: balanced

# Vi du thay the:
# token_profile: burn-max   # Bat tat ca phase, vo hieu hoa 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/claude-haiku-4.5
  planning:    claudible/claude-opus-4.7
  execution:   claudible/claude-sonnet-4.6
  completion:  claudible/gpt-5.4
  subagent:    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   # Khong bi xung dot khi chay tren nhieu branch

models:
  research:    claudible/claude-haiku-4.5
  planning:    claudible/claude-opus-4.7
  execution:   claudible/claude-sonnet-4.6
  completion:  claudible/gpt-5.4
  subagent:    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   # Gui cau hoi len Telegram khi can thiet

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 (tat ca phase, chat luong cao nhat)
# Luu y: dynamic_routing tu dong bi vo hieu hoa, context_selection chuyen sang "full"
version: 1
token_profile: burn-max

models:
  research:    claudible/claude-opus-4.7
  planning:    claudible/claude-opus-4.7
  execution:   claudible/claude-opus-4.7
  completion:  claudible/claude-opus-4.7
  subagent:    claudible/claude-sonnet-4.6

auto_supervisor:
  soft_timeout_minutes: 30   # Tang len vi task phuc tap hon
  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 (tieng Viet co dau)
- 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ỳ.

Á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.