การปรับแต่ง

OpenSpec ให้ระดับการปรับแต่งสามระดับ:

ระดับ	สิ่งที่ทำได้	เหมาะสำหรับ
ค่ากำหนดโปรเจกต์	ตั้งค่าเริ่มต้น, ฉีดบริบท/กฎ	ทีมส่วนใหญ่
สคีมาแบบกำหนดเอง	กำหนดอาร์ติแฟกต์เวิร์กโฟลว์ของคุณเอง	ทีมที่มีกระบวนการเฉพาะตัว
การทับซ้อนระดับโกลบอล	แชร์สคีมาระหว่างทุกโปรเจกต์	ผู้ใช้ขั้นสูง

---

ค่ากำหนดโปรเจกต์

ไฟล์ openspec/config.yaml เป็นวิธีที่ง่ายที่สุดในการปรับแต่ง OpenSpec สำหรับทีมของคุณ ไฟล์นี้ช่วยให้คุณ:

• ตั้งค่าสคีมาเริ่มต้น - ไม่ต้องใส่ --schema ในทุกคำสั่ง
• ฉีดบริบทของโปรเจกต์ - AI เห็นเทคโนโลยีสแต็ก ข้อตกลง ฯลฯ ของคุณ
• เพิ่มกฎต่ออาร์ติแฟกต์ - กฎที่กำหนดเองสำหรับอาร์ติแฟกต์เฉพาะ
• เพิ่มคำแนะนำต่อการดำเนินการ - ความชอบเชิงแนะนำสำหรับงาน apply และ archive
• จำตัวเลือกการผสานรวม - เช่น การเลือกเข้าร่วม GitHub Copilot cloud coding agent

การติดตั้งอย่างรวดเร็ว

openspec init

คำสั่งนี้จะนำทางให้คุณสร้างค่ากำหนดแบบโต้ตอบ หรือคุณสามารถสร้างด้วยตนเอง:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

วิธีการทำงาน

สคีมาเริ่มต้น:

# Without config
openspec new change my-feature --schema spec-driven

# With config - schema is automatic
openspec new change my-feature

การฉีดบริบทและกฎ:

เมื่อสร้างอาร์ติแฟกต์ใดๆ บริบทและกฎของคุณจะถูกฉีดเข้าไปในพรอมต์ของ AI:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• บริบท จะปรากฏในอาร์ติแฟกต์ทั้งหมด
• กฎ จะปรากฏเฉพาะสำหรับอาร์ติแฟกต์ที่ตรงกันเท่านั้น

คำแนะนำการดำเนินการ:

operations.apply.guidance และ operations.archive.guidance เป็นอาร์เรย์ของคำแนะนำเชิง advisory ที่ระบุวิธีการที่เอเจนต์ควรดำเนินการเหล่านั้น คำแนะนำเหล่านี้แยกจาก rules: คำแนะนำการดำเนินการไม่ได้จำกัดเนื้อหาอาร์ติแฟกต์ และกฎอาร์ติแฟกต์จะไม่ถูกเปลี่ยนชื่อเป็นคำแนะนำการดำเนินการ

apply และ archive ดึงข้อมูลเหล่านี้ในช่วงเวลาการทำงาน:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

ทั้งสองรูปแบบจะคืนค่า context ของโปรเจกต์ปัจจุบันและ operationGuidance ที่ตรงกันเป็นฟิลด์แยกที่เป็นตัวเลือก แต่ละครั้งที่เรียกจะอ่าน snapshot ใหม่จากรากที่แก้ไขแล้ว เมื่อเลือก --store <id> ข้อมูลการเปลี่ยนแปลง บริบท และคำแนะนำทั้งหมดจะมาจาก store นั้นแทนที่จะมาจาก repository ปัจจุบัน คำสั่งคำแนะนำ archive เป็นแบบอ่านอย่างเดียว: มันไม่ตรวจสอบหรือผสาน delta specs, ไม่เขียน main specs, ไม่ย้ายการเปลี่ยนแปลง, และไม่รัน workflow archive แบบคงที่

บริบทโปรเจกต์เป็นอินพุตในระดับพรอมต์ที่ต้องมี เวิร์กโฟลว์ที่สร้างขึ้นจะอ่านมันและนำไปใช้กับข้อเท็จจริง ข้อตกลง และข้อจำกัดที่เกี่ยวข้องของโปรเจกต์ คำแนะนำการดำเนินการเป็นคำแนะนำเพิ่มเติมที่เป็นตัวเลือก: เวิร์กโฟลว์จะพิจารณาทุกรายการและปฏิบัติตามรายการที่สอดคล้องและเข้ากันได้กับ workflow ที่มีอยู่แล้ว

ฟิลด์ทั้งสองยังคงแยกออกจากสถานะที่ควบคุมโดย CLI เส้นทางที่แก้ไข ขั้นตอนในตัว ตัวเลือกของผู้ใช้โดยชัดเจน และกฎอาร์ติแฟกต์ เวิร์กโฟลว์จะรายงานความขัดแย้งของบริบทขณะรักษาคุณค่าที่ควบคุมอยู่ มันจะไม่ปฏิบัติตามคำแนะนำที่ไม่เกี่ยวข้องหรือขัดแย้งกัน และจะอธิบายเหตุผล ไม่มีฟิลด์ใดเป็นการตรวจสอบที่บังคับใช้ได้ และเวิร์กโฟลว์จะไม่คัดลอกข้อความของพวกเขาไปยังไฟล์การใช้งาน specs อาร์ติแฟกต์การเปลี่ยนแปลง หรือสรุป เว้นแต่ผู้ใช้จะขอเนื้อหานั้นโดยเฉพาะ

ความปลอดภัยของอินพุต archive และ spec-sync:

archive, bulk archive และ sync แบบ standalone ใช้ artifactPaths.specs.existingOutputPaths จาก openspec status --json เป็นแหล่งเดียวของ delta-spec สคีมาที่ไม่มีอาร์ติแฟกต์ specs หรือการเปลี่ยนแปลงwhose รายการเอาต์พุตที่เป็นรูปธรรมว่างเปล่า ไม่มีอะไรให้ sync; อาร์ติแฟกต์อื่น ๆ ไม่ได้ถูกใช้เพื่ออนุมาน delta specs

ก่อนที่ semantic merge จะเขียน main spec เวิร์กโฟลว์จะบริโภคเอาต์พุตจาก openspec instructions specs --change <name> --json ปัจจุบัน กฎ specs ที่คืนค่ามาจะจำกัดเฉพาะ main specs ที่ผลิตโดยการผสาน那次นั้นเพียงอย่างเดียว Single archive ส่งผ่าน snapshot นั้นเข้าไปใน inline sync, standalone sync ดึงมันโดยตรง, และ bulk archive ได้รับทุก snapshot ที่จำเป็นก่อนการเขียน spec ครั้งแรก การตอบสนอง archive/specs instruction ที่เป็น JSON ไม่เป็นศูนย์หรือไม่ถูกต้องถือเป็นความล้มเหลวในการค้นหา ไม่ใช่ อินพุตว่างเปล่า: เวิร์กโฟลว์จะหยุดก่อนการเขียน spec ที่ได้รับผลกระทบหรือการย้ายการเปลี่ยนแปลง (สำหรับ bulk archive ก่อนการเขียนหรือย้ายชุดข้อมูลใดๆ)

ค่ากำหนดนี้ไม่เปลี่ยนเฟสการทำงานของ archive, พรอมต์ของผู้ปฏิบัติงาน, การดำเนินการระบบไฟล์,ความเป็นเจ้าของ semantic merge, คำสั่ง openspec archive โดยตรง, หรือโครงสร้างและเอาต์พุตของ rules อาร์ติแฟกต์

ลำดับการแก้ไขสคีมา

เมื่อ OpenSpec ต้องการสคีมา มันจะตรวจสอบตามลำดับนี้:

1. โฟลเดอร์ CLI: --schema <name>
2. เมตาเดตาของการเปลี่ยนแปลง (.openspec.yaml ในโฟลเดอร์การเปลี่ยนแปลง)
3. ค่ากำหนดโปรเจกต์ (openspec/config.yaml)
4. ค่าเริ่มต้น (spec-driven)

---

สคีมาแบบกำหนดเอง (Custom Schemas)

เมื่อการกำหนดค่าโปรเจกต์ไม่เพียงพอ คุณสามารถสร้างสคีมาของคุณเองพร้อมเวิร์กโฟลว์ที่กำหนดเองได้อย่างสมบูรณ์ สคีมาแบบกำหนดเองจะอยู่ในไดเรกทอรี openspec/schemas/ ของโปรเจกต์และถูกควบคุมเวอร์ชันพร้อมกับโค้ดของคุณ

your-project/
├── openspec/
│   ├── config.yaml        # การกำหนดค่าโปรเจกต์
│   ├── schemas/           # สคีมาแบบกำหนดเองอยู่ที่นี่
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # การเปลี่ยนแปลงของคุณ
└── src/

Fork สคีมาที่มีอยู่

วิธีที่เร็วที่สุดในการปรับแต่งคือการ fork สคีมาในตัว:

openspec schema fork spec-driven my-workflow

คำสั่งนี้จะคัดลอกสคีมา spec-driven ทั้งหมดไปยัง openspec/schemas/my-workflow/ ซึ่งคุณสามารถแก้ไขได้ตามต้องการ

สิ่งที่คุณจะได้รับ:

openspec/schemas/my-workflow/
├── schema.yaml           # นิยามของเวิร์กโฟลว์
└── templates/
    ├── proposal.md       # เทมเพลตสำหรับ artifact แบบ proposal
    ├── spec.md           # เทมเพลตสำหรับ specs
    ├── design.md         # เทมเพลตสำหรับ design
    └── tasks.md          # เทมเพลตสำหรับ tasks

ตอนนี้ให้แก้ไข schema.yaml เพื่อเปลี่ยนเวิร์กโฟลว์ หรือแก้ไขเทมเพลตเพื่อเปลี่ยนสิ่งที่ AI สร้างขึ้น

สร้างสคีมาตั้งแต่เริ่มต้น

สำหรับเวิร์กโฟลว์ใหม่ทั้งหมด:

# แบบโต้ตอบ (Interactive)
openspec schema init research-first

# แบบไม่โต้ตอบ (Non-interactive)
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

โครงสร้างของสคีมา

สคีมานิยามถึง artifacts ในเวิร์กโฟลว์ของคุณและความสัมพันธ์ระหว่างกัน:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

ฟิลด์สำคัญ:

ฟิลด์	จุดประสงค์
id	ตัวระบุที่ไม่ซ้ำกัน ใช้ในคำสั่งและกฎต่างๆ
generates	ชื่อไฟล์ผลลัพธ์ (รองรับรูปแบบ glob เช่น specs/**/*.md)
template	ไฟล์เทมเพลตในไดเรกทอรี templates/
instruction	คำสั่งสำหรับ AI ในการสร้าง artifact นี้
requires	ความสัมพันธ์เชิงพึ่งพา - artifacts อื่นๆ ที่ต้องมีก่อน

เรียงลำดับ artifacts ตามลำดับที่คุณต้องการให้เขียน requires จะตัดสินความเป็นไปได้; ลำดับของรายการ artifacts: จะตัดสินว่าอะไรเกิดขึ้นก่อนเมื่อมีหลาย artifacts พร้อมกันในครั้งเดียว

เทมเพลต

เทมเพลตคือไฟล์ markdown ที่นำทาง AI ไฟล์เหล่านี้จะถูกแทรกเข้าสู่ prompt เมื่อสร้าง artifact นั้นๆ

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

เทมเพลตสามารถประกอบด้วย:

• หัวข้อส่วนที่ AI ควรเติมข้อมูล
• คอมเมนต์ HTML ที่มีคำแนะนำสำหรับ AI
• ตัวอย่างรูปแบบที่แสดงโครงสร้างที่คาดหวัง

ตรวจสอบความถูกต้องของสคีมาของคุณ

ก่อนใช้สคีมาแบบกำหนดเอง ให้ตรวจสอบความถูกต้อง:

openspec schema validate my-workflow

การดำเนินการนี้จะตรวจสอบ:

• ไวยากรณ์ของ schema.yaml ถูกต้อง
• เทมเพลตที่อ้างอิงทั้งหมดมีอยู่จริง
• ไม่มีความสัมพันธ์เชิงพึ่งพาแบบวนซ้ำ (circular dependencies)
• ID ของ artifacts ถูกต้อง

ใช้สคีมาแบบกำหนดเองของคุณ

หลังจากสร้างแล้ว ให้ใช้สคีมาของคุณด้วย:

# ระบุในคำสั่ง
openspec new change feature --schema my-workflow

# หรือตั้งค่าเป็นค่าเริ่มต้นใน config.yaml
schema: my-workflow

แก้ไขปัญหาการแก้รหัสchema (Debug Schema Resolution)

ไม่แน่ใจว่ากำลังใช้สคีมาใด? ตรวจสอบด้วย:

# ดูว่าสคีมาเฉพาะเจาะจงมาจากที่ใด
openspec schema which my-workflow

# แสดงรายการสคีมาทั้งหมดที่มีอยู่
openspec schema which --all

ผลลัพธ์จะแสดงว่าสคีมากจากโปรเจกต์ของคุณ ไดเรกทอรีผู้ใช้ หรือแพ็กเกจ:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

หมายเหตุ: OpenSpec ยังรองรับสคีมาในระดับผู้ใช้ที่ ~/.local/share/openspec/schemas/ สำหรับการแชร์ข้ามโปรเจกต์ แต่แนะนำให้ใช้สคีมาในระดับโปรเจกต์ใน openspec/schemas/ เนื่องจากถูกควบคุมเวอร์ชันพร้อมกับโค้ดของคุณ

---

ตัวอย่าง

เวิร์กโฟลว์การทำซ้ำอย่างรวดเร็ว (Rapid Iteration Workflow)

เวิร์กโฟลว์ขั้นต่ำสำหรับการทำซ้ำอย่างรวดเร็ว:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

เพิ่ม Artifact สำหรับการตรวจสอบ (Review)

Fork ค่าเริ่มต้นและเพิ่มขั้นตอนการตรวจสอบ:

openspec schema fork spec-driven with-review

จากนั้นแก้ไข schema.yaml เพื่อเพิ่ม:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

สคีมาจากชุมชน

OpenSpec ยังรองรับสคีมาที่ดูแลโดยชุมชนซึ่งแจกจ่ายผ่านรีโพสิทอรีแยกต่างหาก สิ่งเหล่านี้ให้เวิร์กโฟลว์ที่มีมุมมองชัดเจน (opinionated workflows) ซึ่งผสานรวม OpenSpec กับเครื่องมือหรือระบบอื่นๆ คล้ายกับวิธีการทำงานของ แคตตาล็อกส่วนขยายชุมชนของ github/spec-kit สำหรับ spec-kit

สคีมาจากชุมชนไม่ได้ถูกฝังไว้ในแกนหลักของ OpenSpec — พวกมันอยู่ในรีโพสิทอรีของตนเองพร้อมวงจรการเผยแพร่ของตนเอง ในการใช้งาน ให้คัดลอกชุดสคีมาลงในไดเรกทอรี openspec/schemas/<schema-name>/ ของโปรเจกต์คุณ (README ของแต่ละรีโพสิทอรีมีคำแนะนำในการติดตั้ง)

สคีมา	ผู้ดูแล	รีโพสิทอรี	คำอธิบาย
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	จับความตั้งใจของการเปลี่ยนแปลง พฤติกรรมที่สังเกตได้ การออกแบบทางเทคนิค และการตัดสินใจด้านสถาปัตยกรรมที่ยั่งยืน ก่อนการนำไปปฏิบัติ เพิ่มแฟ้มแสดงการตรวจสอบ ADR ระดับการเปลี่ยนแปลงเฉพาะ และเขียนการตัดสินใจที่มีอายุยืนยาวซึ่งผ่านการคัดเลือกเป็น ADRs ที่ไม่สามารถเปลี่ยนแปลงได้และสามารถแทนที่ได้
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	ผสานรวมการกำกับดูแล artifact ของ OpenSpec กับทักษะการดำเนินการของ obra/superpowers (การระดมสมอง, การเขียนแผน, TDD ผ่าน subagents, การตรวจสอบโค้ด, การเสร็จสิ้น) เพิ่ม artifact retrospective ที่เน้นหลักฐานก่อน ซึ่งเติมช่องว่างที่ Superpowers ไม่ได้ครอบคลุมตามธรรมชาติ
nanopm	@nmrtn	nmrtn/nanopm	เวิร์กโฟลว์ที่เน้น PM เป็นหลัก รันเส้นทางการวางแผนของ nanopm (การตรวจสอบ → กลยุทธ์ → แผนงาน → PRD) ข้างต้นของการนำไปปฏิบัติ สะพานเชื่อมการวางแผนผลิตภัณฑ์เข้ากับเวิร์กโฟลว์วิศวกรรมที่ขับเคลื่อนด้วยสเปกของ OpenSpec อ่าน artifacts จาก .nanopm/ หากมีอยู่ — proposal ดึงข้อมูลจากการตรวจสอบ, design ดึงข้อมูลจากกลยุทธ์, และ tasks ดึงข้อมูลจากการแตกย่อย PRD
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	คู่มือการทดสอบแบบ end-to-endในระดับความสามารถ แต่ละความสามารถจะมีสเปกที่ไม่สามารถเปลี่ยนแปลงได้ เทมเพลต tasks ที่ไม่สามารถเปลี่ยนแปลงได้ และบันทึกการทำงานหนึ่งรายการต่อครั้งที่มีการรัน Assertions จะเป็นเพียงพฤติกรรมที่สังเกตได้ (สถานะ HTTP, เนื้อหาการตอบสนอง, สถานะที่เก็บถาวร — ไม่เคยเป็นซับสตริงของล็อก); แต่ละการรันจะบันทึกเวลาเริ่มต้น/สิ้นสุด UTC, ระยะเวลา, และการประมาณการใช้โทเค็น LLM ที่ดีที่สุด
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	เวิร์กโฟลว์ที่ขับเคลื่อนด้วยสเปกพร้อมวินัย TDD และขั้นตอนการตรวจสอบแบบต่อต้าน กระบวนการ: proposal → specs → design → review → test-plan → tasks → apply → verify review เขียนโดยผู้ตรวจสอบแบบอ่านอย่างเดียวที่มีบริบทใหม่ (โมเดลที่สองเมื่อมี) และปล่อยบรรทัด VERDICT: เพื่อบอกเอเจนต์ให้ปิดกั้น test-plan, tasks, และ apply; OpenSpec ตรวจสอบเพียงว่า artifacts มีอยู่จริง ดังนั้นจึงควรบังคับใช้การปิดกั้นด้วย CI หรือ hook ของคุณเอง test-plan映射 ทุกสถานการณ์ของสเปกไปยังชื่อการทดสอบและเป็นสมุดบัญชีแดง/เขียวคู่ที่ verify ตรวจสอบ

ต้องการมีส่วนร่วมในสคีมาชุมชนหรือไม่? เปิด issue พร้อมลิงก์ไปยังรีโพสิทอรีของคุณ หรือส่ง PR เพื่อเพิ่มแถวในตารางนี้

---

ดูเพิ่มเติม

• CLI Reference: Schema Commands - เอกสารประกอบคำสั่งเต็มรูปแบบ