การใช้ OpenSpec ในโปรเจกต์ที่มีอยู่แล้ว

คุณไม่จำเป็นต้องจัดทำเอกสารของโค้ดเบสทั้งหมดตั้งแต่ต้น คุณควรเขียน specs เฉพาะสำหรับส่วนที่คุณกำลังจะเปลี่ยนแปลงเท่านั้น นี่คือสิ่งสำคัญที่สุดที่ควรรู้เกี่ยวกับการนำ OpenSpec มาใช้ในโปรเจกต์ที่มีอยู่แล้ว และเป็นเหตุผลว่าทำไม่อาการออกแบบจึงเน้นไปที่ brownfield เป็นอันดับแรก

ความกังวลทั่วไปมักจะเป็นแบบนี้: "แอปของฉันมีอายุ 80,000 บรรทัด ฉันต้องเขียน specs สำหรับทั้งหมดก่อน OpenSpec ถึงจะใช้งานได้หรือไม่?" คำตอบคือ ไม่ คุณคงไม่ชอบสิ่งนั้น และเราก็เช่นกัน OpenSpec จะค่อย ๆ ขยาย specs ของคุณไปทีละการเปลี่ยนแปลง การเปลี่ยนแปลงครั้งแรกของคุณจะจัดทำเอกสารส่วนที่มันสัมผัส การเปลี่ยนแปลงถัดไปก็จะจัดทำเอกสารส่วนของมัน และเมื่อเวลาผ่านไป specs ของคุณก็จะถูกเติมเต็มโดยธรรมชาติรอบงานที่คุณทำจริง

คู่มือนี้แสดงวิธีการเริ่มต้นตั้งแต่ Day One โดยไม่ต้องพยายามแก้ไขทุกอย่างพร้อมกัน

เวอร์ชันสามสิบวินาที

$ cd your-existing-project
$ openspec init          # adds openspec/ and your AI tool's commands

จากนั้น ใน AI chat ของคุณ:

/opsx:explore            # optional: have the AI read the area you'll touch
/opsx:propose <a real, small change you actually need>
/opsx:apply
/opsx:archive

specs ของคุณจะอธิบายถึงส่วนของระบบที่การเปลี่ยนแปลงนั้นสัมผัสอย่างชัดเจน และไม่มีอะไรมากกว่านั้น นั่นคือสิ่งที่ถูกต้อง คุณไม่ต้องกังวลเกี่ยวกับ 80,000 บรรทัดที่เหลืออีกต่อไป

ทำไม่อาการออกแบบแบบ delta-first จึงเป็นเคล็ดลับทั้งหมด

OpenSpec Changes ถูกเขียนขึ้นในรูปแบบของ deltas: ADDED, MODIFIED, REMOVED Delta อธิบายว่าอะไรกำลังเปลี่ยนแปลงเมื่อเทียบกับพฤติกรรมปัจจุบัน ไม่ใช่ระบบทั้งหมด

นี่คือสิ่งที่งาน brownfield ต้องการอย่างแท้จริง คุณไม่ได้สร้างสิ่งต่าง ๆ ขึ้นมาจากศูนย์บ่อยนัก คุณอาจกำลังเพิ่มฟิลด์ แก้ไขการเปลี่ยนเส้นทาง (redirect) หรือจำกัดเวลา (timeout) การใช้ delta ช่วยให้คุณระบุการเปลี่ยนแปลงนั้นได้อย่างแม่นยำโดยไม่ต้องเขียน specs ความยาว 40 หน้าของทุกสิ่งที่เกี่ยวข้องกับมันก่อน

ดังนั้นไดเรกทอรี openspec/specs/ ของคุณจึงไม่ได้เริ่มต้นด้วยข้อมูลที่เต็มและสมบูรณ์ แต่มันจะเกือบว่างเปล่าและค่อย ๆ สะสม การเปลี่ยนแปลงที่ถูกเก็บถาวน์ (archived) แต่ละครั้งจะรวม delta ของมันเข้าไว้ specs สำหรับ auth/ จะมีความละเอียดถี่ถ้วนก็ต่อเมื่อคุณทำการเปลี่ยนแปลง auth หลายครั้ง ซึ่งเป็นช่วงเวลาที่คุณต้องการให้มันละเอียดถี่ถ้วนพอดี

หากคุณต้องการทราบกลไกานี้เพิ่มเติม โปรดดู Concepts: Delta Specs

การเปลี่ยนแปลงแรกของคุณในโค้ดเบสจริง

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

Step 1: ให้ AI อ่านส่วนที่เกี่ยวข้อง นี่คือจุดที่ /opsx:explore มีประโยชน์อย่างมากเมื่อต้องเจอกับโค้ดเบสที่ไม่คุ้นเคยหรือมีขนาดใหญ่ ชี้มันไปที่ส่วนที่คุณกำลังจะสัมผัสและปล่อยให้มันทำแผนภาพว่าสิ่งต่าง ๆ ทำงานอย่างไรก่อนที่จะเสนออะไรใด ๆ

You: /opsx:explore

AI:  What would you like to explore?

You: I need to add rate limiting to our public API, but I'm not sure
     how requests currently flow through the middleware.

AI:  Let me trace it... [reads the router, middleware stack, and config]
     Requests hit Express, pass through auth middleware, then your
     controllers. There's no rate-limiting layer today. The cleanest
     insertion point is a middleware right after auth. Want me to scope it?

สังเกตว่า AI เข้าใจโครงสร้างจริงของคุณแล้ว ดังนั้นข้อเสนอที่มันเขียนขึ้นจะเข้ากับโค้ดของคุณ ไม่ใช่เทมเพลตทั่วไป ในโค้ดเบสขนาดใหญ่ นิสัยเดียวนี้ช่วยลดความเจ็บปวดได้มากที่สุด ดู Explore First

Step 2: เสนอการเปลี่ยนแปลง ข้อเสนอและ delta spec ของมันจะบันทึกเฉพาะการเปลี่ยนแปลงนี้เท่านั้น

You: /opsx:propose add-api-rate-limiting

Step 3: สร้างและเก็บถาวน์ (Archive) ด้วย /opsx:apply และ /opsx:archive เช่นเดียวกับการเปลี่ยนแปลงใด ๆ หลังจากการเก็บถาวน์ คุณจะมี specs จริงสำหรับพฤติกรรม rate-limiting ของคุณ ซึ่งเกิดขึ้นจากการเปลี่ยนแปลงที่คุณจำเป็นต้องทำอยู่แล้ว

ต้องการการแนะนำแบบมีไกด์นำทางหรือไม่? ใช้ onboard

หากคุณต้องการดูวงจรทั้งหมดที่เกิดขึ้นกับโค้ดของคุณเองพร้อมคำบรรยาย คำสั่ง /opsx:onboard ที่ขยายออกจะทำสิ่งนั้นอย่างแม่นยำ: มันจะสแกนโค้ดเบสของคุณเพื่อหาการปรับปรุงเล็ก ๆ ที่ปลอดภัย จากนั้นจะนำคุณผ่านขั้นตอนการเสนอ การสร้าง และการเก็บถาวน์ โดยอธิบายแต่ละขั้นตอน

เปิดใช้งานคำสั่งที่ขยายออกก่อน:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

จากนั้นใน chat:

/opsx:onboard

นี่คือการแนะนำที่อ่อนโยนที่สุดสำหรับโปรเจกต์จริง และมันจะทิ้งให้คุณได้การเปลี่ยนแปลง (เล็ก ๆ) ที่แท้จริงซึ่งคุณสามารถเก็บไว้หรือทิ้งไป ดู Commands: /opsx:onboard

"แต่ฉันมีเอกสารข้อกำหนดอยู่แล้ว"

บางทีคุณอาจมี PRD, SRS, specs อย่างเป็นทางการ หรือแม้กระทั่งโมเดล TLA+ ดีมาก คุณไม่จำเป็นต้องนำเข้าทั้งหมด และก็ไม่ควรทิ้งมันไปเช่นกัน

ให้ถือว่าเอกสารที่มีอยู่คือ วัตถุดิบสำหรับการสำรวจ ไม่ใช่ specs ที่ต้องแปลง เมื่อคุณเริ่มการเปลี่ยนแปลง ให้วางหรือชี้ AI ไปที่ส่วนที่เกี่ยวข้อง และปล่อยให้มันสร้าง delta OpenSpec ที่มุ่งเน้นจากสิ่งนั้น Delta จะบันทึกพฤติกรรมที่คุณกำลังเปลี่ยนอยู่ในรูปแบบข้อกำหนดและสถานการณ์ที่สามารถทดสอบได้ของ OpenSpec เอกสารต้นฉบับของคุณจะยังคงอยู่เป็นพื้นหลัง

เหตุผลที่ตรงไปตรงมา: Specs ของ OpenSpec ถูกออกแบบให้ยึดตามพฤติกรรมก่อน (behavior-first) และจำกัดขอบเขตตามการเปลี่ยนแปลง PRD 40 หน้าคือ artifact ที่แตกต่างกันโดยมีหน้าที่ต่างออกไป การบังคับแปลงแบบเหวี่ยงแหครั้งเดียวมักจะสร้าง specs ขนาดใหญ่ที่ล้าสมัยและไม่มีใครเชื่อถือได้ การปล่อยให้ specs เติบโตขึ้นจากการเปลี่ยนแปลงจริง ๆ จะทำให้มันแม่นยำอยู่เสมอ

You: /opsx:explore
You: Here's the section of our PRD about checkout. I'm implementing the
     "guest checkout" requirement next.
     [paste the relevant requirement]
AI:  [reads it, asks clarifying questions, then helps scope a change]
You: /opsx:propose add-guest-checkout

การจัดระเบียบ specs ในโค้ดเบสขนาดใหญ่

Specs จะถูกเก็บไว้ภายใต้ openspec/specs/ โดยแบ่งตาม โดเมน (domain) ซึ่งเป็นพื้นที่เชิงตรรกะที่ตรงกับวิธีที่ทีมของคุณคิดเกี่ยวกับระบบ คุณไม่จำเป็นต้องออกแบบ Taxonomy ทั้งหมดตั้งแต่ต้น สร้างโฟลเดอร์โดเมนเมื่อการเปลี่ยนแปลงแรกในพื้นที่นั้นต้องการมัน

วิธีการทั่วไปในการแบ่งโดเมน:

• ตามขอบเขตคุณสมบัติ (feature area): auth/, payments/, search/
• ตามคอมโพเนนต์ (component): api/, frontend/, workers/
• ตามบริบทที่มีขอบเขตจำกัด (bounded context): ordering/, fulfillment/, inventory/

เลือกสิ่งที่ทำให้ผู้ที่เพิ่งเข้ามาใหม่พยักหน้า คุณสามารถปรับปรุงในภายหลัง ดู Concepts: Specs

Monorepos และงานที่ครอบคลุมหลาย Repositories

สำหรับ monorepo รูปแบบที่ง่ายที่สุดคือมีไดเรกทอรี openspec/ หนึ่งแห่งที่รากของ repo โดยมีโดเมนที่แมปกับ packages หรือ services ของคุณ สิ่งนี้ครอบคลุมทีมส่วนใหญ่แล้ว

หากงานของคุณครอบคลุม หลาย repositories อย่างแท้จริง (หรือหลายแพ็กเกจที่คุณถือว่าเป็นสิ่งที่แยกจากกัน) OpenSpec มีฟีเจอร์ stores แบบ beta: การวางแผนจะอยู่ใน repo ที่เป็นอิสระซึ่งโค้ด repo ใด ๆ ของคุณสามารถอ้างถึงได้ ดังนั้น แผนจึงไม่จำเป็นต้องอยู่ภายใน openspec/ ของ repo เดียว มันยังเป็นเวอร์ชันเบต้า ดังนั้นให้ปฏิบัติต่อคำสั่งและสถานะของมันว่ากำลังพัฒนาอยู่ เริ่มต้นด้วย Stores User Guide สำหรับแบบจำลองทางความคิดและเส้นทางที่มีประโยชน์ที่สุด

ข้อควรระวังที่ต้องซื่อสัตย์สักสองสามข้อ

• ต้านทานแรงกระตุ้นที่จะเติมเต็มทุกอย่าง (back-fill) การเขียน specs สำหรับโค้ดที่คุณไม่ได้เปลี่ยนแปลงนั้นรู้สึกว่ามีประสิทธิภาพแต่โดยปกติแล้วไม่ใช่เช่นนั้น Specs เหล่านั้นจะล้าสมัย เพราะไม่มีอะไรบังคับให้มันติดตามความเป็นจริง ให้การเปลี่ยนแปลงจริงขับเคลื่อน specs ของคุณ
• รักษาการเปลี่ยนแปลงในช่วงต้นให้เล็ก การเปลี่ยนแปลงสองสามครั้งแรกของคุณเป็นเรื่องของการเรียนรู้จังหวะงานมากพอ ๆ กับการส่งมอบ ขอบเขตที่กระชับทำให้วงจรเร็วและบทเรียนมีราคาถูก
• Commit openspec/ ไปยัง git Specs และ archive ของคุณควรอยู่ใน version control ควบคู่ไปกับโค้ดที่มันอธิบาย
• ให้บริบทแก่ AI ในโค้ดเบสขนาดใหญ่ที่มีข้อตกลงที่เป็นมาตรฐาน ให้กรอก context: ใน openspec/config.yaml เพื่อให้ทุกข้อเสนอเคารพต่อ stack และรูปแบบของคุณ ดู Customization

จะไปที่ไหนต่อไป

• Explore First - นิสัยสำคัญสำหรับการทำความเข้าใจโค้ดก่อนที่คุณจะเปลี่ยนแปลงมัน
• Getting Started - การเดินผ่านการเปลี่ยนแปลงครั้งแรกอย่างสมบูรณ์
• Editing & Iterating on a Change - การปรับเปลี่ยนขณะที่กำลังเรียนรู้
• Concepts: Delta Specs - ทำไมเดลต้าจึงทำให้งาน brownfield สะอาด
• Customization - สอน OpenSpec เกี่ยวกับข้อตกลงของโปรเจกต์คุณ