การใช้งาน OpenSpec ในทีม

เนื้อหาในคู่มืออื่นทั้งหมดทำงานได้เหมือนกันไม่ว่าคุณจะทำงานคนเดียวหรืออยู่ในทีมที่มี 20 คน สิ่งที่เปลี่ยนแปลงเมื่อทำงานในทีมคือคำถามรอบๆ ขอบ: สเปคจะถูกจัดเก็บอยู่ที่ไหน, เพื่อนร่วมทีมจะตรวจสอบแผนอย่างไร, และทั้งหมดนี้เข้ากันได้อย่างไรกับกระบวนการ pull request ที่เรามีอยู่แล้ว?

คำตอบสั้น: การเปลี่ยนแปลงก็แค่เป็นไฟล์เท่านั้น และ OpenSpec ไม่เคยแตะต้อง git เลย ดังนั้นมันจึงเข้ากันได้กับกระบวนการทำงานปัจจุบันของคุณแทนที่จะแทนที่มัน หน้านี้จะระบุสัญญาประเภทต่างๆ ที่ใช้งานได้ดี

กฎเดียว: OpenSpec ไม่แตะต้อง git

OpenSpec จะอ่านและเขียนไฟล์ Markdown ธรรมดาทั้งหมดภายใต้โฟลเดอร์ openspec/ เท่านั้น มันไม่เคย commit, สร้าง branch, push, หรือ pull ในโปรเจกต์ของคุณ — และไม่เคย clone หรือ sync store ด้วยตัวเอง นั่นหมายความว่า:

• คุณ commit โฟลเดอร์ openspec/ เหมือนกับไฟล์ซอร์สอื่นๆ สเปค, การเปลี่ยนแปลงที่กำลังดำเนินการ, และโฟลเดอร์ archive เป็นส่วนหนึ่งของประวัติโปรเจกต์ของคุณ (ใช่, commit โฟลเดอร์ทั้งหมด — ดูเพิ่มเติมที่ FAQ)
• การเปลี่ยนแปลงก็แค่เป็นโฟลเดอร์ที่คุณจัดการเวอร์ชันเหมือนโค้ด openspec/changes/add-dark-mode/ ก็แค่เป็นไฟล์บน branch เท่านั้น
• ทั้งหมดที่เขียนต่อจากนี้เป็นสัญญาประเภท ไม่ใช่ข้อบังคับที่บังคับใช้ OpenSpec จะไม่บังคับให้คุณทำตามวิธีนี้; มันแค่เข้ากันได้อย่างลื่นไหลเท่านั้น

กระบวนการทำงานประจำวัน

กระบวนการทำงานที่ใช้งานได้ดีจะเป็นการ map การเปลี่ยนแปลงไปยัง branch และ pull request:

git switch -c add-dark-mode        เริ่มต้นสร้าง branch ตามปกติ
   │
/opsx:propose add-dark-mode        เขียนร่างแผน (proposal + specs + tasks)
   │
ตรวจสอบแผน                        อ่านแผนก่อนที่จะเขียนโค้ดใดๆ — ดูที่ การตรวจสอบการเปลี่ยนแปลง
   │
/opsx:apply                        สร้างออกมา; artifacts และโค้ดที่เปลี่ยนแปลงอยู่ด้วยกัน
   │
git commit && open a PR            PR จะมีทั้ง spec delta และโค้ด
   │
เพื่อนร่วมทีมตรวจสอบและ merge
   │
/opsx:archive                      รวม delta เข้าไปใน specs/, ย้ายโฟลเดอร์การเปลี่ยนแปลงไปยัง archive/

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

การตรวจสอบสเปคใน pull request

ทีมจะรู้สึกถึงประโยชน์ที่ได้จากตรงนี้ เมื่อ PR มีสเปค delta ของการเปลี่ยนแปลงอยู่ด้วย ผู้ตรวจสอบจะได้รับสิ่งที่ diff ดิบไม่เคยให้给他们เลย: คำอธิบายด้วยภาษาทั่วไปว่าการเปลี่ยนแปลงนี้มีไว้ทำอะไร ก่อนที่เขาจะอ่านบรรทัดโค้ดแม้แต่บรรทัดเดียว

ลำดับการตรวจสอบที่ดีสำหรับผู้ตรวจสอบคือ:

1. อ่าน proposal.md — ปัญหาและขอบเขตของงานนี้ถูกต้องหรือไม่?
2. อ่าน delta ภายใต้ specs/ — ความหมายของ "เสร็จสมบูรณ์" ถูกกำหนดอย่างถูกต้องหรือไม่? (นี่คือขั้นตอนตรวจสอบ 2 นาทีของ การตรวจสอบการเปลี่ยนแปลง ที่กำลังเกิดขึ้นใน PR ณ ตอนนี้)
3. จากนั้นอ่าน diff ของโค้ด — โค้ดตรงนี้ตอบสนองความต้องการเหล่านั้นอย่างถูกต้องหรือไม่?

ผู้ตรวจสอบที่ไม่เห็นด้วยกับ วิธีการทำงาน สามารถระบุไว้ที่ proposal ได้อย่างง่ายดาย แทนที่จะต้องโต้กลับกันอีกครั้งบน 300 บรรทัดของโค้ด วางสเปค delta ไว้ใกล้ส่วนบนของรายละเอียด PR, หรือชี้ผู้ตรวจสอบไปที่โฟลเดอร์การเปลี่ยนแปลง เพื่อให้เขาอ่านเริ่มจากตรงนั้น

ควรเก็บลง archive เมื่อใด

การเก็บลง archive จะรวม delta ของการเปลี่ยนแปลงเข้าไปใน openspec/specs/ หลักของคุณ และย้ายโฟลเดอร์การเปลี่ยนแปลงไปยัง openspec/changes/archive/YYYY-MM-DD-<name>/ เนื่องจาก specs/ เป็น แหล่งข้อมูลจริงที่ใช้ร่วมกัน การเลือกเวลาที่เหมาะสมจึงสำคัญสำหรับทีม มีสองสัญญาประเภทที่ใช้งานได้ดี:

• เก็บลง archive หลังจากที่ PR ถูก merge (แนะนำ) branch จะถือการเปลี่ยนแปลงที่กำลังดำเนินการอยู่; หลังจากที่มันถูก merge เข้าไปใน branch หลักของคุณ ให้เก็บลง archive ที่นั่น (มักจะเป็น commit เล็กๆ ที่ตามมา หรือการทำความสะอาดตามกำหนดเวลา) สิ่งนี้ทำให้ specs/ ที่ใช้ร่วมกันขยายไปต่อได้เฉพาะกับงานที่ถูกนำไปใช้งานจริงเท่านั้น
• เก็บลง archive ภายใน PR ง่ายกว่าสำหรับทีมขนาดเล็ก: PR เดียวกันที่เพิ่มโค้ดก็จะทำการ sync และเก็บลง archive ด้วย ข้อเสียคือ diff ของ specs/ และ diff ของโค้ดจะมาพร้อมกัน ซึ่งอาจทำให้ PR มีรายละเอียดมากเกินไป

เลือกวิธีหนึ่งและ保持ความสอดคล้อง ไม่ว่าวิธีไหน /opsx:archive ก็จะตรวจสอบว่ารายการงานทั้งหมดเสร็จสมบูรณ์แล้ว และเสนอให้ทำการ sync ก่อน ดังนั้นจึงไม่มีการ merge งานที่ยังไม่เสร็จสมบูรณ์โดยไม่ตั้งใจ

สองคน, การเปลี่ยนแปลงแบบขนาน

เนื่องจากการเปลี่ยนแปลงแต่ละรายการเป็นโฟลเดอร์แยกกัน จึงไม่เกิดการขัดแย้งระหว่างกัน:

• การเปลี่ยนแปลงคนละรายการ, คนละผู้ดำเนินการ — ไม่มีปัญหา add-dark-mode และ rate-limit-login เป็นโฟลเดอร์คนละอย่างบน branch คนละอย่าง; มันไม่แตะต้องกันเลยจนกว่าทั้งคู่จะถูกเก็บลง archive
• หนึ่งการเปลี่ยนแปลง, เจ้าของคนเดียว สองคนที่แก้ไขโฟลเดอร์การเปลี่ยนแปลงเดียวกันจะเกิดข้อขัดแย้งเหมือนกันทุกประการกับสองคนที่แก้ไขไฟล์เดียวกัน กำหนดให้หนึ่งการเปลี่ยนแปลงมีผู้เขียนคนเดียว, หรือแยกออกเป็นสองการเปลี่ยนแปลง (เป็นอีกเหตุผลหนึ่งที่จะ กำหนดขนาดการเปลี่ยนแปลงให้เหมาะสม)
• จุดเดียวที่ข้อขัดแย้งจะเกิดขึ้นคือ specs/ หากสองการเปลี่ยนแปลงแก้ไข ความต้องการเดียวกัน การเก็บการเปลี่ยนแปลงที่สองลง archive จะเกิดข้อขัดแย้งใน openspec/specs/…/spec.md — แก้ไขเหมือนกับข้อขัดแย้งในการ merge ทั่วไป โดยเก็บความต้องการที่สอดคล้องกับความเป็นจริงไว้ นี่เป็นเรื่องที่หายนาน และถือเป็นฟีเจอร์: git กำลังบอกคุณว่าสองการเปลี่ยนแปลงไม่เห็นด้วยกับวิธีการทำงานของระบบ

เมื่อการวางแผนใหญ่เกินไปสำหรับหนึ่ง repo

ทั้งหมดที่เขียนด้านบนสมมติว่าแผนจะอยู่ในโฟลเดอร์ openspec/ ของ repo โค้ดเอง ซึ่งเป็นค่าเริ่มต้นที่ถูกต้อง เมื่อการวางแผนของคุณจริงๆ ขยายไปข้ามหลาย repo หรือหลายทีม — หนึ่งฟีเจอร์ที่แตะต้องสามบริการ, หรือความต้องการที่หนึ่งทีมเป็นเจ้าของและทีมอื่นใช้งาน — นั่นคือเหตุผลที่ฟีเจอร์ stores เวอร์ชัน beta ถูกสร้างขึ้นมา: การวางแผนจะมี repo ของตัวเองเองที่ repo โค้ดใดๆ ก็สามารถชี้ไปที่ได้ เริ่มต้นด้วย คู่มือผู้ใช้ Stores

ควรไปต่อที่ใด

• การตรวจสอบการเปลี่ยนแปลง — ขั้นตอนตรวจสอบที่กำลังอยู่ใน PR ของคุณ
• การเขียนสเปคที่ดี — รวมถึงวิธีการกำหนดขนาดการเปลี่ยนแปลงให้เหมาะสมเพื่อให้พอดีกับหนึ่ง branch
• คู่มือผู้ใช้ Stores — การวางแผนที่ข้าม repo และทีม