ตั้งค่า foundation.json

ผู้อ่าน: ผู้ดูแลโปรเจกต์และ agent ที่ได้รับอนุญาตให้ตั้งค่า หากต้องการใช้งานตามปกติ เริ่มที่ เริ่มใช้งาน

foundation.json คือ policy ที่ commit ไว้สำหรับหนึ่งโปรเจกต์ มันบอก Change Loop ว่า agent ทำงานอัตโนมัติได้มากแค่ไหน, งานแต่ละแบบควรใช้ model tier ใด, เมื่อไรต้อง escalate, ใครรีวิวได้ และต้องเตรียม Build workspace ใหม่อย่างไร โปรเจกต์ส่วนใหญ่ไม่ต้องแก้ไฟล์นี้ หน้านี้ช่วยเมื่อคุณอยากให้พฤติกรรมใดเปลี่ยนไป

เป้าหมายที่พบบ่อยและค่าที่ต้องแก้

ฉันต้องการ…	ตั้งใน `foundation.json`	หมายเหตุ
ใช้ model อื่นหรือ model ที่ถูกกว่าสำหรับงานบางประเภท	`models.routing: true` แล้วแก้ `models.fast`/`standard`/`deep` `.family`	routing ปิดเป็นค่าเริ่มต้น: ทุก task ใช้ tier `standard` ดูหัวข้อ `models`
ให้ reviewer ต้องไม่ใช่คนเดียวกับผู้ implement	`review.independence: "required"`	identity และ AI session ของ reviewer ต้องต่างกัน
ให้ AI คนละ provider มารีวิว	`review.diversity: "required"` และ `review.defaultReviewer: "codex-sol"` (หรือ `claude-opus` ถ้า Codex เป็นผู้ implement)	ถ้า reviewer ตรงกับผู้ implement จะ fail closed ดูหัวข้อ `review`
รันคำสั่ง setup ของโปรเจกต์ในทุก workspace ใหม่	`sandbox.setupCommand` (และ `sandbox.setupTimeoutMs`)	harness ติดตั้ง dependency จาก lockfile ให้อัตโนมัติ; ตั้ง `sandbox.installDependencies: false` เพื่อปิด
จำกัดค่าใช้จ่ายของหนึ่ง autonomous run	`execution.tokenBudgets.rapid/standard`, `execution.requestBudgets.rapid/standard`	เป็นเพดาน ไม่ใช่เป้าหมาย ตั้ง `execution.budgetWatchdog: true` เพื่อให้ packet มีคำเตือนและขีดจำกัดการใช้จ่าย
ลดจำนวน agent หรือ check ที่รันพร้อมกัน	`execution.maxParallelAgents`, `maxParallelProviders`, `maxParallelSetups`	จำนวนเต็ม 1 ถึง 16
ให้ build ที่ช้ามีเวลามากขึ้น	`execution.leaseMinutes`	1 ถึง 1440 นาที
ให้บทบาทที่ระบุต้องอนุมัติ spec	`approval.roles`	เช่น `["tech-lead", "qa"]` ดูหัวข้อ `approval`
บังคับหลักฐาน coverage และ mutation ใน change เสี่ยงสูง	`quality.changeGate: "warn"` หรือ `"enforce-high-risk"`	ต้องมี quality configuration
ตั้งชื่อ commit และ branch ของ `/deliver`	`deliver.commitSubject`, `deliver.branchPattern`, `deliver.ticketPattern`	ใช้เฉพาะขั้น Deliver ที่ไม่บังคับ

หลังแก้ให้รันตรวจตามหัวข้อ “ขั้นตอนแก้ที่ปลอดภัย”

Reference ฉบับเต็ม

ส่วนที่เหลือของหน้านี้อธิบายทุก field ที่รองรับ foundation.json ไม่ได้เก็บ requirement ของผลิตภัณฑ์หรือสถานะงานปัจจุบัน:

เรื่อง	Source of truth
ผลิตภัณฑ์ควรทำอะไร	`openspec/`
implementation เหลืออะไร	`tasks.md` ใน change ที่ active
runtime state และ receipt	`.foundation/`
Change Loop มีสิทธิ์ execute อย่างไร	`foundation.json`

installer คัดลอกไฟล์นี้ให้เฉพาะตอนที่ยังไม่มี หลังจากนั้นไฟล์เป็นของโปรเจกต์ และ upgrade จะไม่เขียนทับ ควร commit ไว้เพื่อให้ developer กับ reviewer ทุกคน ทำงานภายใต้ policy เดียวกันที่ตรวจสอบได้

Profile เริ่มต้น

profile ปัจจุบันออกแบบให้ Claude Code ตัวเดียวเริ่มใช้งานได้ ใช้ Claude Opus สำหรับ configured review และอนุญาต identity/model family เดียวกัน:

{
  "review": {
    "independence": "self",
    "diversity": "single-model",
    "defaultReviewer": "claude-opus"
  },
  "workflow": {
    "grounding": "optional",
    "reviewCircuit": "full-delta",
    "reviewPolicy": "risk-tiered"
  }
}

ไฟล์จริงยังมี execution budget, model tier, escalation trigger และ reviewer definition ทั้งสองตัว ให้แก้ object เดิม อย่าแทนทั้งไฟล์ด้วยตัวอย่างย่อด้านบน

self กับ single-model เป็น waiver ที่ประกาศตรง ๆ ไม่ได้แปลว่า review นั้น independent หรือ diverse receipt จะบันทึก independence-waived-self-review และ diversity-waived-single-model เพื่อให้ trade-off ตรวจสอบย้อนหลังได้

ขั้นตอนแก้ที่ปลอดภัย

แก้ foundation.json ที่ root และคง version เป็น 1
รัน claude-foundation doctor --stage change เพื่อตรวจ policy ทั่วไป
ถ้าแก้ review ให้รัน claude-foundation doctor --stage prove เพื่อตรวจ CLI, authentication และ read-only mode ของ reviewer
ดู model routing ด้วย claude-foundation models
commit policy ก่อนสร้าง evidence ภายใต้นโยบายใหม่

การเปลี่ยน policy อาจทำให้ review หรือ proof ที่สร้างด้วย contract เก่า stale ให้รัน readiness และ Prove ใหม่ อย่าแก้ receipt ด้วยมือ

`execution`: กำหนดขอบเขต autonomous run

{
  "execution": {
    "maxParallelAgents": 3,
    "maxParallelProviders": 4,
    "maxParallelSetups": 3,
    "packetBytes": {
      "task": 20480,
      "review": 20480,
      "repository": 24576,
      "global": 32768
    },
    "tokenBudgets": { "rapid": 800000, "standard": 1600000 },
    "requestBudgets": { "rapid": 100, "standard": 200 },
    "maxContinuationWindows": 3,
    "planSummaryBytes": 4096,
    "leaseMinutes": 45
  }
}

Field	ค่าที่ใช้ได้	ปรับเมื่อไร
`maxParallelAgents`	จำนวนเต็ม `1..16`	ลดเมื่อเครื่องจำกัดหรืองานผูกกันแน่น เพิ่มเฉพาะเมื่อแยก task ได้ปลอดภัย
`maxParallelProviders`	จำนวนเต็ม `1..16`	จำกัด provider หลักฐานและ service startup ที่เป็นอิสระต่อกัน
`maxParallelSetups`	จำนวนเต็ม `1..16`	จำกัด setup command ของ repository ที่รันพร้อมกันระหว่างเตรียม Build
`packetBytes.*`	จำนวนเต็ม `2048..65536` byte	เพิ่มเมื่อ task, review, repository description หรือ packet ทั้งก้อนถูกตัดจริง ๆ การอัปเกรดจะแทนค่าเริ่มต้นเดิมแบบตรงตัว (`8192/8192/12288/16384`) ด้วยค่าปัจจุบัน และคงค่าที่ปรับเองไว้
`tokenBudgets.rapid/standard`	จำนวนเต็ม `10000..100000000`	จำกัด token ของ autonomous run หนึ่งรอบ เป็นเพดาน ไม่ใช่เป้าหมาย
`requestBudgets.rapid/standard`	จำนวนเต็ม `10..100000`	จำกัดจำนวน model request ต่อ run
`maxContinuationWindows`	จำนวนเต็ม `1..20`	จำกัดจำนวน continuation window ที่ operator อนุมัติแยกกัน โดยไม่บังคับงานเดิมที่ยังค้างให้แตกเป็น Change ใหม่
`planSummaryBytes`	จำนวนเต็ม `1024..16384`	จำกัด plan แบบย่อที่ส่งต่อระหว่าง phase
`leaseMinutes`	ตัวเลข `1..1440`	เพิ่มสำหรับ build ช้า หรือลดเพื่อคืนงานจาก worker ที่ค้างเร็วขึ้น

เมื่อใช้ budget ถึง 85% Change Loop จะเข้า completion-only mode และหยุดงาน สำรวจหรือ refactor ที่ไม่จำเป็น เมื่อ change ถึง 100% ครั้งแรก harness จะเปิด window ขนาดเท่าเดิมให้เองหนึ่งครั้งพร้อมบันทึก โดยไม่นับรวมใน maxContinuationWindows เมื่อถึง 100% อีกครั้ง operator สามารถอนุมัติ window ใหม่ แบบมี audit ได้ตราบใดที่ยังมีงานใน scope เดิมค้างอยู่ จนถึงเพดาน maxContinuationWindows ส่วน readiness, receipt reuse, recovery และ archive ยังทำงานต่อได้โดยไม่ต้องขยาย budget

`quality`: เปิด quality gate แบบเป็นขั้น

quality.changeGate รับค่า off, warn หรือ enforce-high-risk โหมด warn จะแจ้งเมื่อ Change ความเสี่ยงสูงไม่มี provider สำหรับ changed-quality (coverage, complexity และ CRAP) หรือ mutation ส่วน enforce จะบังคับทั้งสอง capability สำหรับงาน high-impact หรือ security-sensitive โดยแต่ละภาษาสามารถ ใช้ command adapter ของโครงการเองได้

field นี้เลือก ว่า Change แบบไหนต้องมี quality evidence ส่วนไฟล์ commit แยก quality/foundation-quality.json กำหนด ว่าแต่ละ repository สร้างและประเมิน หลักฐานนั้นอย่างไร ได้แก่ language profile, command, built-in normalizer, threshold, baseline และ exception ให้สร้างไฟล์นี้ด้วย quality init ไม่ใช่เพิ่ม provider command ลง foundation.json ดูรายละเอียดที่ Quality gate ของโปรเจกต์

`models`: route ตามจุดประสงค์ ไม่ผูกกับคำสั่งของ host

{
  "models": {
    "fast": {
      "family": "haiku",
      "fallbackTier": "standard",
      "purposes": ["inventory", "logs", "mechanical-docs"]
    },
    "standard": {
      "family": "sonnet",
      "fallbackTier": "deep",
      "purposes": ["implementation", "tests", "focused-investigation"]
    },
    "deep": {
      "family": "opus",
      "fallbackTier": null,
      "purposes": ["architecture", "security", "migration", "independent-review"]
    }
  }
}

models.routing เป็น boolean และค่าเริ่มต้นคือ false: จนกว่าจะตั้งเป็น true ทุก task จะใช้ tier standard เว้นแต่ task เองขอ tier และตาราง tier ด้านล่างยังไม่มีผลต่อการวางแผน

key fast, standard และ deep คือ portable tier ส่วน family ระบุ family ที่ต้องการ ขณะที่ native agent host เป็นตัวรัน model จริง fallbackTier ต้องเป็น หนึ่งในสาม tier หรือ null และ deep ห้าม fallback ลง tier ต่ำกว่า

ควรรักษา purpose list ให้แคบ change ความเสี่ยงสูงต้อง escalate ตาม boundary แม้ diff จะเล็ก การใส่งานทุกแบบไว้ใน fast ไม่ได้ทำให้งาน security หรือ migration กลายเป็น low risk

`escalation`: เงื่อนไขที่ต้องใช้ judgment ลึกขึ้น

trigger เริ่มต้นมีดังนี้:

ambiguous-contract — behavior หรือสิ่งที่ไม่รวมใน scope ยังไม่ชัด;
auth-or-sensitive-data — เกี่ยวข้องกับ authorization, secret หรือข้อมูลอ่อนไหว;
migration — ต้องย้าย persistent state หรือ compatibility อย่างปลอดภัย;
concurrency — ordering, race, retry หรือ idempotency มีผล;
public-compatibility — public interface หรือ behavior ที่ support อาจเปลี่ยน;
cross-repository-conflict — scope หรือ version ระหว่าง repository ขัดกัน;
evidence-anomaly — evidence หาย ขัดแย้ง หรือ stale ผิดคาด;
two-failed-attempts — approach ปัจจุบันล้มเหลวสองครั้งแล้ว

escalation เลือก investigation หรือ review ที่ลึกขึ้น มันไม่ขยาย write authority, ข้าม budget หรือเปลี่ยน credential ภายนอกให้เป็น permission ของ agent

`review`: เลือกความสะดวกหรือ separation of duties

review มีสองแกนที่แยกจากกัน:

Field	ผ่อนปรน	เข้มงวด
`independence`	`self`: identity/session เดียวกันรีวิวได้	`required`: identity และ AI session ต้องต่างกัน
`diversity`	`single-model`: provider/family อื่นเป็นเพียง preferred	`required`: AI reviewer ต้องมาจากคนละ provider และ model family

ค่า default: Claude installation เดียว

{
  "review": {
    "independence": "self",
    "diversity": "single-model",
    "defaultReviewer": "claude-opus"
  }
}

profile นี้เริ่มง่ายที่สุด configured review ผ่าน authority run ยังคงเป็น read-only และ ephemeral แต่ policy ไม่บังคับ identity หรือ model family ที่ต่างกัน

Model เดิม แต่แยก reviewer session

{
  "review": {
    "independence": "required",
    "diversity": "single-model",
    "defaultReviewer": "claude-opus"
  }
}

ใช้เมื่อมี provider เดียว แต่รับ self-review ไม่ได้

Review ข้าม provider

ถ้า implement ด้วย Claude:

{
  "review": {
    "independence": "required",
    "diversity": "required",
    "defaultReviewer": "codex-sol"
  }
}

ถ้า implement ด้วย Codex ให้เลือก claude-opus แทน เมื่อ diversity เป็น required reviewer ต้องต่างจาก implementation provenance จริง ไม่เช่นนั้น receipt จะ fail closed

reviewer definition อยู่ใต้ review.reviewers โดย reviewer ที่ตั้งค่าต้อง:

ใช้ adapter claude-cli หรือ codex-cli คู่กับ provider family ที่ถูกต้อง;
ระบุ executable ที่ติดตั้งแล้วและ model ID;
ใช้ reasoningEffort: "high" (fast tier ของงานความเสี่ยงต่ำรันที่ medium);
ใช้ sandbox: "read-only" และ ephemeral: true

อย่าใส่ credential, token หรือ login command ใน foundation.json ให้ติดตั้งและ login CLI ตามปกติ แล้วใช้ doctor --stage prove ตรวจ readiness

`approval`: approval lane ตามบทบาท

ไม่บังคับ ใช้กำหนดให้ role ที่ระบุต้องอนุมัติ spec แยกกัน:

{
  "approval": {
    "roles": ["tech-lead", "qa"]
  }
}

roles รับค่าที่ไม่ซ้ำกันจาก product-owner, tech-lead, qa, devops และ security ค่าเริ่มต้นคือว่าง: อนุมัติ spec ครั้งเดียวเหมือนเดิม

เมื่อตั้งค่าแล้ว change ต้องได้รับอนุมัติจาก role ที่ตั้งไว้ซึ่ง router เลือกสำหรับ change นั้น แต่ละ role อนุมัติด้วย claude-foundation advance <change> --approve-spec --role <role> --decision-ref <ref> (หรือ change resolve … --approve-spec --role <role>) จนกว่าทุก lane ที่ต้องมีจะ อนุมัติ revision และ packet ปัจจุบันครบ advance จะหยุดด้วย ASK_USER พร้อมระบุ role ที่ยังขาด และไม่สร้าง sandbox การอนุมัติที่ไม่มี --role ครอบคลุมทุก lane ที่ต้องมี ณ ตอนที่อนุมัติ และการอนุมัติด้วย --role ภายหลังจะเพิ่ม lane นั้นโดยไม่ยกเลิก การอนุมัติเดิม harness บันทึก role ตามที่แจ้งและไม่ได้ยืนยันตัวตน revision ที่เพิ่ม อย่างเดียวคงการอนุมัติของ lane ไว้ แต่ถ้าทำให้ router เลือก role ใหม่ role นั้นต้องอนุมัติ ก่อน Build ส่วน revision ที่ลบ requirement จะรีเซ็ตทุก lane role ที่ไม่รู้จัก การใช้ --role โดยไม่ได้ตั้ง approval.roles, approval ที่ไม่ใช่ object หรือ roles ที่ไม่ใช่ array จะถูกปฏิเสธ

`sandbox`: เตรียม Build workspace ใหม่

Git worktree มี tracked file แต่ไม่มี node_modules ถ้าไม่มี setup command Harness จะติดตั้ง dependency เองจาก lockfile ของ workspace (npm ci หรือคำสั่ง frozen-lockfile ของ pnpm, yarn, bun) ตั้ง "installDependencies": false เพื่อปิด ถ้า setup ต้องทำอย่างอื่น ให้เพิ่ม setup command ที่ deterministic:

{
  "sandbox": {
    "setupCommand": "npm ci",
    "setupTimeoutMs": 600000
  }
}

setupCommand ต้องเป็น string ที่ไม่ว่าง setupTimeoutMs ต้องเป็นจำนวนเต็ม ตั้งแต่ 1000 ถึง 3600000 และ installDependencies ต้องเป็น boolean คำสั่งรัน หนึ่งครั้งในทุก workspace ใหม่ ถ้าล้มเหลว Change Loop จะเก็บ workspace ไว้ retry ให้ แล้วส่งต่อให้ agent พร้อมคำสั่ง directory และ log แทนที่จะทำต่อใน sandbox ที่เตรียม ไม่ครบ

โปรเจกต์หลาย repository ให้เก็บ root setup ไว้ที่นี่ และใส่ setup เฉพาะ repo ใน openspec/repositories.yaml topology, scope ของ change, scope ของ provider และลำดับ Land เป็นคนละ contract ให้ตั้งค่าตามลำดับในคู่มือ Workflow หลาย Repository

`workflow`: ใช้ control circuit รุ่นปัจจุบัน

{
  "workflow": {
    "grounding": "optional",
    "reviewCircuit": "full-delta",
    "reviewPolicy": "risk-tiered"
  }
}

grounding รับ required หรือ optional;
reviewCircuit รับ full-delta หรือค่า compatibility legacy;
reviewPolicy รับ risk-tiered หรือค่า compatibility legacy

งานใหม่ควรใช้ค่าที่ ship มา ค่า legacy มีไว้สำหรับอ่านโปรเจกต์เก่า ไม่ใช่วิธีที่ แนะนำสำหรับลดความเข้มของ review optional แปลว่า semantic compiler สร้าง grounding.yaml เฉพาะเมื่อมี material non-derived decision จริง ตั้งเป็น required เมื่อ policy ของ project ต้องมี decision ledger ทุก change เท่านั้น เพราะ grounding ว่างไม่ได้เพิ่มคุณภาพ

`deliver`: ตั้งชื่อ commit และ branch ของ pull request (ไม่บังคับ)

ใช้เฉพาะกับ /deliver ค่าเริ่มต้นคือ feat: <title> (หรือ fix: <title>) และ change/<change-id>:

{
  "deliver": {
    "commitSubject": "{commitType}({ticket}): {title}",
    "branchPattern": "feature/{ticket}-{title}",
    "ticketPattern": "[A-Z]+-\\d+"
  }
}

placeholder ที่ใช้ได้คือ {changeId}, {title}, {commitType}, {prType} และ {ticket} ซึ่งคือ match แรกของ ticketPattern ใน change id, title หรือ proposal ถ้ามี placeholder ที่ไม่รู้จัก pattern ไม่ถูกต้อง หา ticket ไม่เจอ หรือได้ subject หรือ branch ที่ใช้ไม่ได้ Deliver จะหยุดเป็น wait แบบ delivery-policy ก่อน commit ใด ๆ ให้แก้การตั้งค่าแล้วสั่ง /deliver อีกครั้ง กฎการตั้งชื่อฉบับเต็มอยู่ใน WORKFLOW.md (/deliver <change>)

field อื่น ๆ

Field	ค่าเริ่มต้น	ความหมาย
`execution.budgetWatchdog`	`false`	Boolean ถ้า `false` ยังบันทึก usage แต่ packet ไม่มี spend directive หรือขีดจำกัด; ถ้า `true` จะมี signal `budget-warning` เมื่อใช้ถึง 70%
`review.fallbackReviewers`	`["codex-sol", "main-session"]` ในไฟล์ที่ติดตั้ง	reviewer ที่ลองตามลำดับเฉพาะเมื่อเกิด infrastructure error; verdict `fail` หรือ `inconclusive` ไม่ trigger fallback ชื่อต้องมีอยู่จริง ห้ามซ้ำ `defaultReviewer` และ `main-session` ต้องใช้คู่กับ `independence: "self"`
`review.infraFailureThreshold`	`2` ในไฟล์ที่ติดตั้ง	จำนวนเต็ม `1..5`
`telemetry.requireUsage`	`true` ในไฟล์ที่ติดตั้ง	Boolean; Land ต้องมี usage dimension ที่วัดได้จริง
`land.riskBasedCi`	`false`	Boolean ดู contract ของ signed CI ใน EVIDENCE.md
`workflow.handoffDefaultOwner`	`"devops-team"`	ชื่อทีมที่ไม่ว่างสำหรับ handoff ที่ต้องมีสิทธิ์

จุดที่พลาดบ่อย

แทนทั้งไฟล์ด้วยตัวอย่างย่อ ให้แก้ object เดิมเพื่อรักษา reviewer definition และ policy section อื่นไว้
มอง budget เป็นโควตา change เล็กควรจบโดยใช้ต่ำกว่าเพดานมาก
บังคับ diversity แต่เลือก model family เดียวกับ implementer review receipt จะ fail อย่างถูกต้อง
ให้ deep fallback ไป fast หรือ standard runtime จะปฏิเสธการ downgrade
ใส่ secret ใน setup หรือ reviewer field เก็บ secret ออกจาก committed policy และใช้ authentication ปกติของ CLI
คาดว่า upgrade จะเปลี่ยน policy โปรเจกต์ installer รักษาไฟล์นี้หลังสร้างครั้งแรก ต้องอัปเดตโดยตั้งใจและ review diff

หลังแก้ทุกครั้ง ชุดตรวจที่สั้นและเชื่อถือได้คือ:

claude-foundation doctor --stage change
claude-foundation doctor --stage prove
claude-foundation models