เริ่มต้นใช้งาน

การเปลี่ยนแปลงครั้งแรกของคุณ ตั้งแต่ไอเดียจนถึงการจัดเก็บ ในโปรเจกต์ใหม่หรือโปรเจกต์ที่มีอยู่

ก่อนเริ่มต้น คุณต้องมี CLI บนเครื่องของคุณ (การติดตั้ง) และต้องเริ่มต้นใช้ OpenSpec ในโปรเจกต์ของคุณ (ตั้งค่าโปรเจกต์ของคุณ)

เริ่มต้นจากโปรเจกต์เปล่า

คุณสามารถเริ่มต้นได้โดยไม่ต้องเลือก stack หรือสถาปัตยกรรมที่สมบูรณ์ เริ่มต้นใช้ OpenSpec ในโฟลเดอร์โปรเจกต์ของคุณ จากนั้นขอให้ agent ของคุณสำรวจตัวเลือกร่วมกับคุณ ในแชท AI ของคุณ:

ช่วยฉันสำรวจระบบติดตามงาน (task tracker) ตั้งแต่ต้น ฉันยังไม่ได้เลือก stack เปรียบเทียบตัวเลือกต่างๆ และช่วยฉันเลือกพฤติกรรมแรกที่จะสร้าง

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

วงจรการทำงานโดยภาพรวม

การเปลี่ยนแปลงทุกครั้งผ่านห้าขั้นตอนเดียวกัน: คุณคิดไอเดียร่วมกับ agent ของคุณ มันร่างแผน คุณแก้ไขแผนก่อนที่จะมีโค้ดใดๆ เกิดขึ้น agent สร้างจากแผนนั้น และการจัดเก็บจะอัปเดตสเปกของคุณด้วยสิ่งที่นำไปใช้จริง

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

ทุกพร้อมต์ด้านล่างใส่ในแชท AI ของคุณ ซึ่งเป็นที่เดียวกันกับที่คุณขอโค้ด ตัวอย่างต่างๆ ใช้ภาษาธรรมดาเพื่อให้ใช้งานได้กับเครื่องมือต่างๆ คุณยังสามารถเรียกใช้ skill โดยตรงได้ โดยไวยากรณ์จะแตกต่างกันไปตามเครื่องมือ (เครื่องมือที่รองรับ)

ขั้นตอนที่ 1: Explore

คิดไอเดียร่วมกับ agent ของคุณก่อนที่จะขอแผน ในแชท AI ของคุณ:

ช่วยฉันสำรวจว่าควรใช้ rate limiting ในแอปนี้อย่างไร

Explore เป็นโหมดการคิด โดย agent จะตรวจสอบโค้ดเบสของคุณ ถามคำถามที่สำคัญ ร่างตัวเลือกต่างๆ และท้าทายสมมติฐาน มันไม่เขียนโค้ด มันไม่เขียนอะไรอื่นเลยเว้นแต่คุณจะขอให้บันทึกสิ่งที่คุณตัดสินใจ หรือตอบตกลงเมื่อมันเสนอ ผลลัพธ์คือไอเดียที่คมขึ้น

อยู่ที่นี่นานเท่าที่ปัญหาต้องการ เมื่อรูปร่างดูเหมาะสมแล้ว ให้มอบหมายต่อ:

เสนอการเปลี่ยนแปลงที่เราเพิ่งพูดคุยกัน

บรรทัดนั้นจะเริ่ม propose ให้คุณ โดยนำสิ่งที่คุณตกลงกันทั้งหมดไปด้วย ข้ามพร้อมต์แรกในขั้นตอนที่ 2

ขั้นตอนที่ 2: Propose

Propose เปลี่ยนไอเดียให้เป็นแผนที่ตรวจสอบได้ หากมาจาก explore มันจะทำงานต่อโดยอัตโนมัติ หากเริ่มใหม่ เมื่อการเปลี่ยนแปลงชัดเจนในใจคุณ ให้ขอโดยตรง ในแชท AI ของคุณ:

เสนอการเปลี่ยนแปลงเพื่อเพิ่ม rate limiting

agent จะถามสิ่งที่ต้องการ จากนั้นเขียนโฟลเดอร์ change:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

ยังไม่มีโค้ด Propose หยุดอยู่ที่แผน

ขั้นตอนที่ 3: ตรวจสอบและแก้ไขแผน

แก้ไขแผนขณะที่ยังเป็นตัวอักษรและยังไม่มีอะไรถูกสร้างขึ้น อ่านตามลำดับนี้:

• proposal.md: นี่คือปัญหาที่ถูกต้องหรือไม่ ที่ขนาดที่เหมาะสมหรือไม่?
• specs/: ส่วนที่มีค่าที่สุดในการอ่าน คุณจะยอมรับข้อกำหนดเหล่านี้ว่าเสร็จสมบูรณ์หรือไม่?
• tasks.md: งานต่างๆ ครอบคลุมสเปกทั้งหมดหรือไม่ และไม่มีอะไรเกินจากนั้น?

ในการแก้ไข ทั้งสองวิธีใช้ได้:

• แก้ไขไฟล์ด้วยตัวเอง ผลลัพธ์เหล่านี้เป็น markdown ธรรมดา และไฟล์เหล่านั้นคือแผน
• บอก agent ของคุณว่าอะไรผิด ("สเปกขาดกรณีที่ไม่ได้รับการยืนยันตัวตนไว้") มันจะแก้ไขผลลัพธ์

ขั้นตอนที่ 4: Apply

Apply เปลี่ยนแผนให้เป็นโค้ด เริ่มเซสชันแชทใหม่ เนื่องจากการนำไปใช้จริงจะทำงานได้ดีกว่าบนหน้าต่างบริบทที่สะอาด ในแชท AI ของคุณ:

Apply the add-rate-limiting change.

agent จะอ่านโฟลเดอร์ change จากนั้นทำงานตาม tasks.md โดยทำเครื่องหมายเช็คแต่ละงานเมื่อเสร็จสิ้น

• ถูกขัดจังหวะ หรือหมดบริบท? เปิดเซสชันใหม่และขอให้ apply อีกครั้ง มันจะทำงานต่อจากงานแรกที่ยังไม่ได้เช็ค
• แผนปรากฏว่าผิด? แก้ไขผลลัพธ์ (ด้วยวิธีใดวิธีหนึ่งจากขั้นตอนที่ 3) จากนั้นทำ apply ต่อ
• ความคืบหน้า อยู่ที่ช่องเช็คใน tasks.md ไม่มีสถานะที่ซ่อนอยู่

ขั้นตอนที่ 5: Archive

การจัดเก็บทำสองอย่าง: มันอัปเดตสเปกหลักของคุณด้วยข้อกำหนดของการเปลี่ยนแปลง และย้ายโฟลเดอร์ change ไปยังโฟลเดอร์ archive (ใน /openspec/changes/archive/*)

เมื่อทุกช่องใน tasks.md ถูกเช็คแล้ว ในแชท AI ของคุณ:

Archive the add-rate-limiting change.

ขั้นตอนการจัดเก็บมีดังนี้:

## การเปลี่ยนแปลงที่เสร็จสมบูรณ์
> การนำไปใช้จริงเสร็จแล้ว สเปกเดลต้า (สิ่งที่การเปลี่ยนแปลงนี้เพิ่มเข้ามา) ยังคงอยู่ในโฟลเดอร์ change; specs/ ยังไม่รู้จัก rate limiting
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## ข้อกำหนดไปอยู่ใน specs/
> ข้อกำหนดแต่ละข้อในเดลต้าจะไปอยู่ในสเปกหลัก: ที่เพิ่มเข้ามาจะถูกผนวก ที่แก้ไขจะแทนที่เวอร์ชันเก่า ความสามารถใหม่จะได้รับไฟล์สเปกใหม่
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## โฟลเดอร์ถูกย้ายไป archive/
> โฟลเดอร์ change ทั้งหมด รวมถึงเดลต้า ถูกย้ายเข้าไปใน archive โดยมีคำนำหน้าเป็นวันที่ ไม่มีอะไรถูกลบ
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## สเปกอธิบายระบบตามที่สร้างขึ้นจริง
> changes/ ว่างเปล่าสำหรับการเปลี่ยนแปลงครั้งต่อไป specs/ เป็นแหล่งความจริงของสิ่งที่ระบบทำ; archive/ เป็นประวัติของวิธีที่ระบบเป็นอยู่
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git เป็นเรื่องแยกต่างหาก คอมมิตโฟลเดอร์ change ร่วมกับโค้ด และไม่มีอะไรในเวิร์กโฟลว์ของคุณเปลี่ยนแปลง

เก็บหรือตัดแต่งการเปลี่ยนแปลงที่จัดเก็บแล้ว

openspec/changes/archive/ เก็บ proposal, design, tasks และเดลต้าสำหรับการเปลี่ยนแปลงที่เสร็จสมบูรณ์แต่ละครั้ง ในขั้นตอน archive ด้านบน เดลต้าได้อัปเดต openspec/specs/ แล้ว

• เก็บโฟลเดอร์ change ทั้งหมด เมื่อคุณต้องการบันทึกที่สมบูรณ์ในตัวเองใน checkout ปัจจุบัน
• ลบโฟลเดอร์ specs/ ของการเปลี่ยนแปลงที่จัดเก็บแล้ว เมื่อ Git เป็นประวัติสเปกของคุณ คอมมิต archive ก่อน จากนั้นลบ openspec/changes/archive/<change>/specs/ proposal, design และ tasks จะยังคงอยู่ใน checkout openspec validate --archived ยังคงทำงานได้เพราะมันตรวจสอบความสมบูรณ์ของงาน ไม่ใช่เดลต้าที่นำไปใช้
• ลบโฟลเดอร์ change ทั้งหมด เฉพาะเมื่อคุณไม่ต้องการ proposal, design หรือประวัติงานของมันอยู่ใน checkout อีกต่อไป สเปกปัจจุบันจะไม่เปลี่ยนแปลง แต่ openspec validate --archived และการค้นหาใน checkout จะไม่รวมการเปลี่ยนแปลงนั้นอีกต่อไป

WARNING

เก็บคอมมิต archive ไว้ในประวัติ repository ของคุณ หากคุณต้องการให้ Git เก็บไฟล์ที่ถูกลบไว้ การรวมคอมมิต archive และคอมมิตการจัดเก็บเข้าด้วยกันจะลบสแน็ปช็อตระหว่างกลางนั้นออก

OpenSpec ไม่ตัดแต่งการเปลี่ยนแปลงที่จัดเก็บแล้วโดยอัตโนมัติหรือจัดหาการตั้งค่าการเก็บรักษา

เรียนรู้เพิ่มเติม

• Delta specs: วิธีเขียนการเปลี่ยนแปลงพฤติกรรมในสเปกเดลต้า
• Profiles: เวิร์กโฟลว์เสริมนอกเหนือจากชุดหลัก (ตรวจสอบก่อน archive, การวางแผนแบบเพิ่มพูน)

คู่มือขั้นสูง

ยังไม่ได้เขียน คู่มือที่เราวางแผนเพิ่มเติม:

• Prototype first: ทดลองสร้างโค้ดก่อนสเปกใดๆ จากนั้นเติม proposal จากสิ่งที่ prototype สอนคุณ
• Building iteratively: ชุดของการเปลี่ยนแปลงเล็กๆ แทน proposal ใหญ่ครั้งเดียว
• Revising an implemented change: แผนต้องเคลื่อนไหวอีกครั้งหลัง apply แต่การเปลี่ยนแปลงยังไม่ได้ merge หรือ archive