สร้างแผนทางเทคนิคโดยละเอียด

ข้อมูลจําเพาะกําหนดสิ่งที่คุณต้องสร้าง แผนทางเทคนิคกําหนดวิธีที่คุณสร้าง หน่วยนี้ครอบคลุมเทคนิคการวางแผนขั้นสูงสําหรับสถานการณ์บราวน์ฟิลด์ขององค์กร

ทบทวนพื้นฐานของแผน

ไฟล์ plan.md ทําหน้าที่เป็นเอกสารการออกแบบของคุณเชื่อมช่องว่างระหว่างข้อกําหนดระดับสูงใน spec.md และงานการดําเนินงานที่เป็นรูปธรรมที่ตามมา แผนทางเทคนิคที่ครอบคลุมประกอบด้วย:

• ภาพรวมสถาปัตยกรรม: มุมมองระดับสูงของวิธีที่ส่วนประกอบโต้ตอบ
• กลุ่มเทคโนโลยีและการตัดสินใจที่สําคัญ: เอกสารที่ชัดเจนเกี่ยวกับตัวเลือกเทคโนโลยีพร้อมเหตุผล
• ลําดับการใช้งาน: ความคืบหน้าเชิงตรรกะของขั้นตอนการใช้งาน
• การตรวจสอบรัฐธรรมนูญ: ตรวจสอบอย่างชัดเจนว่าโซลูชันที่เสนอนั้นสอดคล้องกับหลักการของโครงการ
• สมมติฐานและคําถามเปิด: เอกสารสมมติฐานและคําถามที่ยังไม่ได้รับการแก้ไข

เมื่อคํานึงถึงพื้นฐานเหล่านี้ เรามาสํารวจข้อควรพิจารณาในการวางแผนขั้นสูงสําหรับการพัฒนาองค์กรกัน

การแยกข้อกังวล - ข้อมูลจําเพาะกับแผน

การแยกข้อกังวลระหว่างข้อกําหนดและแผนทางเทคนิคเป็นสิ่งสําคัญ แม้ว่าข้อมูลจําเพาะจะยังคงเสถียรและมุ่งเน้นไปที่ "อะไร" แต่แผนสามารถพัฒนาได้เมื่อคุณทดลองกับแนวทาง "อย่างไร" ที่แตกต่างกัน

สมมติว่าข้อมูลจําเพาะของคุณต้องการคุณลักษณะการอัปโหลดเอกสารสําหรับพอร์ทัลพนักงานภายใน ข้อมูลจําเพาะกําหนดความต้องการของผู้ใช้: ขีดจํากัดขนาดไฟล์ รูปแบบที่รองรับ คําติชมการอัปโหลด และการควบคุมการเข้าถึง แผนทางเทคนิคแปลข้อกําหนดเหล่านี้เป็นการตัดสินใจทางสถาปัตยกรรมที่เป็นรูปธรรม: บริการที่เก็บข้อมูล Azure ที่จะใช้ วิธีจัดโครงสร้าง API กลไกการรับรองความถูกต้องที่จะนําไปใช้ และวิธีตรวจสอบความถูกต้องของไฟล์ หากคุณตัดสินใจที่จะเปลี่ยนจากเทคโนโลยีหนึ่งไปเป็นอีกเทคโนโลยีหนึ่ง เช่น การย้ายจากที่เก็บข้อมูล Azure Blob ไปยังไฟล์ Azure คุณจะอัปเดต plan.md ในขณะที่ spec.md ยังคงไม่เปลี่ยนแปลงเป็นส่วนใหญ่ ข้อกําหนดของคุณลักษณะจะไม่เปลี่ยนแปลง มีการเปลี่ยนแปลงเฉพาะแนวทางการใช้งานเท่านั้น

ตรวจสอบโครงสร้างและเนื้อหาของแผน

แผนทางเทคนิคที่ครอบคลุมประกอบด้วยส่วนสําคัญหลายส่วนที่กําหนดแนวทางการใช้งานของคุณโดยรวม

ภาพรวมสถาปัตยกรรม

ภาพรวมสถาปัตยกรรมให้มุมมองระดับสูงของวิธีที่ส่วนประกอบโต้ตอบ สําหรับคุณสมบัติการอัปโหลดเอกสาร สถาปัตยกรรมอาจอธิบาย:

"ใช้ปลายทาง /api/documents/upload API แบ็คเอนด์ใหม่เพื่อจัดการการอัปโหลดไฟล์แบบหลายส่วน ส่วนหน้าของ React มีคอมโพเนนต์ DocumentUpload ใหม่พร้อมตัวเลือกไฟล์และตัวบ่งชี้ความคืบหน้า เมื่อผู้ใช้เลือกไฟล์ ส่วนหน้าจะตรวจสอบขนาดและประเภทก่อนอัปโหลด ส่วนหลังได้รับไฟล์ ตรวจสอบความถูกต้องอีกครั้ง จัดเก็บไว้ในที่เก็บข้อมูล Azure Blob และบันทึกข้อมูลเมตาในฐานข้อมูล SQL หลังจากอัปโหลดสําเร็จส่วนหน้าจะรีเฟรชรายการเอกสารเพื่อแสดงไฟล์ใหม่"

บทสรุปนี้สร้างโฟลว์โดยรวมโดยไม่ต้องเจาะลึกรายละเอียดระดับโค้ด ช่วยให้มั่นใจได้ว่าทุกคนเข้าใจองค์ประกอบหลักและการโต้ตอบ

กลุ่มเทคโนโลยีและการตัดสินใจที่สําคัญ

แผนนี้จัดทําเอกสารทางเลือกและเหตุผลด้านเทคโนโลยีอย่างชัดเจน ส่วนนี้ป้องกันความสับสนในอนาคตว่าเหตุใดจึงเลือกห้องสมุดหรือบริการเฉพาะ

ตัวอย่างการตัดสินใจด้านเทคโนโลยี:

• ส่วนหลัง: .NET 8 Web API พร้อม Azure.Storage.Blobs SDK v12 สําหรับการดําเนินการ Blob
• ส่วนหน้า: React 18 ด้วยคอมโพเนนต์อัปโหลดของ Ant Design เพื่อความสอดคล้องของ UI
• การรับรองความถูกต้อง: ใช้โทเค็น Microsoft Entra ID ที่มีอยู่จากบริบทการรับรองความถูกต้องของพอร์ทัล
• ที่เก็บข้อมูล: คอนเทนเนอร์ที่เก็บข้อมูล Azure Blob ชื่อ employee-documents.
• ฐานข้อมูล: ขยายฐานข้อมูล SQL ที่มีอยู่ด้วยตาราง DocumentMetadata (คอลัมน์: Id, UserId, FileName, BlobUrl, UploadDate, FileSize)

การตัดสินใจแต่ละครั้งควรสอดคล้องกับข้อกําหนดข้อกําหนดและหลักการของรัฐธรรมนูญ หากรัฐธรรมนูญของคุณกําหนดให้ "ใช้บริการ Azure สําหรับทรัพยากรระบบคลาวด์ทั้งหมด" แผนจะเลือกที่เก็บข้อมูล Azure Blob อย่างชัดเจนและอ้างอิงหลักการนี้

ลําดับการใช้งาน

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

ลําดับการใช้งานทั่วไปสําหรับคุณลักษณะการอัปโหลดเอกสาร:

1. การอัปเดตสคีมาฐานข้อมูล: สร้างตาราง DocumentMetadata ด้วยดัชนีและข้อจํากัดที่เหมาะสม
2. การพัฒนา API ส่วนหลัง: ใช้ปลายทาง POST /api/documents/upload พร้อมการตรวจสอบไฟล์ การรวมที่เก็บข้อมูล Blob และการคงอยู่ของข้อมูลเมตา
3. การสร้างคอมโพเนนต์ส่วนหน้า: สร้างคอมโพเนนต์ DocumentUpload ด้วยการเลือกไฟล์ การตรวจสอบฝั่งไคลเอ็นต์ และการแสดงความคืบหน้าในการอัปโหลด
4. บูรณาการ: ต่อสายส่วนประกอบส่วนหน้าเข้ากับ API ส่วนหลัง จัดการการตอบกลับ และอัปเดตรายการเอกสาร
5. การเสริมความแข็งแกร่งด้านความปลอดภัย: ใช้การตรวจสอบความถูกต้องของประเภทไฟล์ฝั่งเซิร์ฟเวอร์ การจํากัดขนาด และการตรวจสอบความถูกต้อง
6. การจัดการข้อผิดพลาด: เพิ่มข้อความแสดงข้อผิดพลาดที่ครอบคลุมสําหรับความล้มเหลวของไคลเอ็นต์และฝั่งเซิร์ฟเวอร์
7. การทดสอบ: สร้างการทดสอบหน่วยสําหรับวิธีการ API และการทดสอบการผสานรวมสําหรับขั้นตอนการอัปโหลด

ลําดับนี้ช่วยให้แน่ใจว่าองค์ประกอบพื้นฐาน (สคีมาฐานข้อมูล) มีอยู่ก่อนที่จะมีการใช้ส่วนประกอบที่ขึ้นต่อกัน (API ที่เขียนไปยังฐานข้อมูล) แต่ละขั้นตอนสร้างขึ้นจากงานก่อนหน้านี้ ซึ่งช่วยลดโอกาสที่จะเกิดปัญหาการบูรณาการ

การตรวจสอบรัฐธรรมนูญ

แผนประกอบด้วยส่วนการตรวจสอบที่ตรวจสอบวิธีแก้ปัญหาที่เสนออย่างชัดเจนกับรัฐธรรมนูญ การตรวจสอบนี้ป้องกันการล่องลอยทางสถาปัตยกรรมและรับประกันความสอดคล้องกับหลักการของโครงการ

หากรัฐธรรมนูญของคุณมี "ที่เก็บข้อมูลทั้งหมดต้องใช้บริการ Azure" และ "API ต้องตรวจสอบอินพุตทั้งบนไคลเอ็นต์และเซิร์ฟเวอร์" ส่วนการตรวจสอบแผนจะยืนยัน:

• "การใช้ที่เก็บข้อมูล Azure Blob เป็นไปตามข้อกําหนดของบริการ Azure"
• "การใช้การตรวจสอบความถูกต้องทั้งในคอมโพเนนต์ React (ไคลเอ็นต์) และ .NET API (เซิร์ฟเวอร์) สอดคล้องกับหลักการรักษาความปลอดภัยในการป้องกันเชิงลึก"
• "ตรงตามข้อกําหนดการรับรองความถูกต้องของ Microsoft Entra ID โดยใช้บริบทการรับรองความถูกต้องของพอร์ทัลที่มีอยู่"

การตรวจสอบนี้ทําหน้าที่เป็นจุดตรวจ หากแผนเสนอบางสิ่งที่ละเมิดรัฐธรรมนูญ AI มักจะตั้งค่าสถานะ หรือคุณสังเกตเห็นระหว่างการตรวจสอบ การจัดการกับความขัดแย้งของรัฐธรรมนูญในขั้นตอนแผนจะป้องกันการทําซ้ําในภายหลัง

สมมติฐานและคําถามเปิด

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

ตัวอย่างสมมติฐาน:

• "สมมติว่าคอนเทนเนอร์ Azure Blob Storage 'เอกสารพนักงาน' มีอยู่และได้รับการกําหนดค่าสําหรับการเข้าถึงแบบส่วนตัว"
• "สมมติว่าฐานข้อมูล SQL ที่มีอยู่มีความจุเพียงพอสําหรับข้อมูลเมตา"
• "สมมติว่าการสแกนไวรัสของไฟล์ที่อัปโหลดอยู่นอกขอบเขตสําหรับการทําซ้ํานี้"

ตัวอย่างคําถามเปิด:

• "ผู้ดูแลระบบควรมีความสามารถในการลบเอกสารที่อัปโหลดของผู้ใช้รายอื่นหรือไม่"
• "เราจําเป็นต้องบันทึกการตรวจสอบสําหรับความพยายามในการเข้าถึงเอกสารทั้งหมดหรือไม่"
• "ระบบควรส่งการแจ้งเตือนทางอีเมลเมื่อมีการอัปโหลดเอกสารหรือไม่"

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

สร้างแผนโดยใช้ /speckit.plan

GitHub Spec Kit สร้างแผนผ่าน /speckit.plan คําสั่งใน GitHub Copilot Chat คําสั่งนี้ใช้ทั้ง spec.md และ constitution.md เป็นอินพุตเพื่อสร้างการออกแบบทางเทคนิคที่ครอบคลุม

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

สําหรับคุณลักษณะการอัปโหลดเอกสารในสถานการณ์พอร์ทัลพนักงานภายใน คุณอาจระบุบริบทดังนี้:

"พอร์ทัลที่มีอยู่ใช้ส่วนหน้า React กับแบ็คเอนด์ .NET 8 Web API เราจําเป็นต้องรวมคุณสมบัติการอัปโหลดเข้ากับสแต็กนี้ ใช้ Azure Blob Storage สําหรับการคงอยู่ของไฟล์ ต้องมีการรับรองความถูกต้องของ Microsoft Entra ID สําหรับการดําเนินการอัปโหลดทั้งหมด พอร์ทัลมีฐานข้อมูล SQL ที่พร้อมใช้งานสําหรับการจัดเก็บข้อมูลเมตาอยู่แล้ว"

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

เรียกใช้คําสั่งการวางแผน

เปิด GitHub Copilot Chat ใน Visual Studio Code แล้วป้อน/speckit.plan หาก AI ขอข้อมูลเพิ่มเติม ให้ระบุบริบททางสถาปัตยกรรมของคุณ GitHub Copilot ประมวลผลข้อมูลจําเพาะ รัฐธรรมนูญ และบริบทพิเศษของคุณเพื่อสร้าง plan.md

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

ตรวจสอบและตรวจสอบแผน

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

ตรวจสอบความครอบคลุมของข้อกําหนดข้อมูลจําเพาะ

เปรียบเทียบแผนกับ spec.md อย่างเป็นระบบ ทุกข้อกําหนดในข้อกําหนดควรจับคู่กับแนวทางการนําไปใช้ในแผน

ตัวอย่างเช่น ถ้า spec.md ต้องการ "แสดงข้อความแสดงข้อผิดพลาดสําหรับไฟล์ที่มีขนาดเกิน 50 MB" แผนควรอธิบายว่าการตรวจสอบนี้เกิดขึ้นที่ใดและอย่างไร หากแผนละเว้นการตรวจสอบความถูกต้องนี้ แสดงว่าแผนไม่สมบูรณ์หรือข้อกําหนดต้องการคําชี้แจง

ตรวจสอบความสอดคล้องตามมาตรฐานทางเทคนิค

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

คําถามที่ต้องพิจารณา:

• สถาปัตยกรรมที่เสนอเหมาะสมกับระบบที่มีอยู่หรือไม่
• ไลบรารีที่เลือกได้รับการอนุมัติให้ใช้ในสภาพแวดล้อมของคุณหรือไม่
• ตัวเลือกเทคโนโลยีสอดคล้องกับนโยบายการรักษาความปลอดภัยและการปฏิบัติตามข้อกําหนดขององค์กรหรือไม่
• มีรูปแบบที่กําหนดไว้สําหรับฟังก์ชันการทํางานที่คล้ายคลึงกันที่ควรปฏิบัติตามหรือไม่?

สําหรับคุณลักษณะการอัปโหลดเอกสารในสภาพแวดล้อม Azure ให้ตรวจสอบว่า Azure Blob Storage เป็นบริการที่ได้รับอนุมัติ ว่าวิธีการรับรองความถูกต้องสอดคล้องกับมาตรฐานข้อมูลประจําตัวขององค์กร (เช่น การใช้ Microsoft Entra ID) และ Schema SQL ที่เสนอเป็นไปตามแบบแผนการตั้งชื่อฐานข้อมูล

ตรวจสอบการปฏิบัติตามรัฐธรรมนูญ

แผนควรมีการตรวจสอบอย่างชัดเจนว่าโซลูชันที่เสนอนั้นสอดคล้องกับข้อกําหนดของรัฐธรรมนูญ ตรวจสอบส่วนการยืนยันนี้อย่างรอบคอบเพื่อให้แน่ใจว่าไม่มีการละเมิดหลักการ

ถ้ารัฐธรรมนูญของคุณกําหนดให้ "ข้อมูลลับทั้งหมดต้องถูกเก็บไว้ใน Azure Key Vault" และแผนเสนอการจัดเก็บสตริงการเชื่อมต่อที่เก็บข้อมูล Azure ใน appsettings.jsonแสดงว่ามีข้อขัดแย้ง ควรแก้ไขแผนเพื่อดึงสตริงการเชื่อมต่อจาก Key Vault ในขณะรันไทม์

การละเมิดรัฐธรรมนูญที่ค้นพบระหว่างการวางแผนนั้นง่ายต่อการแก้ไข การละเมิดรัฐธรรมนูญที่ค้นพบระหว่างการตรวจสอบโค้ดหรือการปรับใช้การผลิตมีค่าใช้จ่ายสูงและก่อกวน

ทําซ้ําและปรับแต่งแผน

แผนมักจะต้องมีการปรับแต่งหลังจากการสร้างครั้งแรก อย่าคาดหวังความสมบูรณ์แบบในการลองครั้งแรก ใช้ความสามารถในการชี้แจงของ GitHub Copilot เพื่อปรับปรุงคุณภาพของแผน

จัดการกับความคลุมเครือและช่องว่าง

หากแผนมีข้อความที่คลุมเครือ เช่น "ใช้การจัดการข้อผิดพลาดที่เหมาะสม" ให้กดเพื่อดูข้อมูลเฉพาะ ข้อผิดพลาดใดบ้างที่อาจเกิดขึ้น ข้อผิดพลาดแต่ละข้อควรจัดการอย่างไร? ข้อมูลข้อผิดพลาดใดที่ควรบันทึกเทียบกับการแสดงต่อผู้ใช้

ใช้ GitHub Copilot Chat เพื่อถามคําถามติดตามผล: "ข้อผิดพลาดเฉพาะใดที่ปลายทางการอัปโหลดควรจัดการ" หรือ "จะเกิดอะไรขึ้นหากที่เก็บข้อมูล Azure Blob ไม่พร้อมใช้งาน" AI สามารถขยายส่วนที่คลุมเครือให้เป็นข้อกําหนดที่เป็นรูปธรรม

ตรวจสอบความถูกต้องของความเป็นไปได้ทางเทคนิค

ตรวจสอบว่าสถาปัตยกรรมที่เสนอนั้นเป็นไปได้ในทางเทคนิคตามข้อจํากัดของคุณ หากแผนเสนอให้อัปโหลดไฟล์ 50 MB แบบซิงโครนัสผ่าน Web API ที่มีการหมดเวลา 30 วินาที แสดงว่ามีปัญหาเกิดขึ้น ไฟล์ที่มีขนาดมากกว่า 50 MB อาจต้องมีการอัปโหลดเป็นกลุ่มหรือหมดเวลาที่เพิ่มขึ้น

ปรึกษากับสมาชิกในทีมที่มีความเชี่ยวชาญที่เกี่ยวข้อง ถ้าแผนเสนอการเปลี่ยนแปลง Schema ฐานข้อมูล ให้ตรวจทานกับผู้ดูแลระบบฐานข้อมูล หากต้องใช้ทรัพยากร Azure ใหม่ ให้ตรวจสอบกับวิศวกรโครงสร้างพื้นฐานว่าสามารถเตรียมใช้งานได้

พิจารณาข้อกําหนดที่ไม่ทํางาน

ตรวจสอบให้แน่ใจว่าแผนตอบสนองความต้องการที่ไม่ทํางานจากข้อกําหนด: ประสิทธิภาพ ความปลอดภัย ความสามารถในการปรับขนาด การบํารุงรักษา การเข้าถึง

สําหรับการอัปโหลดเอกสาร ให้ยืนยันว่าแผนประกอบด้วย:

• ประสิทธิภาพ: การอัปโหลดควรเสร็จสมบูรณ์เร็วแค่ไหน ปริมาณการอัปโหลดพร้อมกันสูงสุดคือเท่าใด
• ความปลอดภัย: ไฟล์ถูกสแกนหามัลแวร์อย่างไร มีการควบคุมการเข้าถึงอย่างไร บันทึกการตรวจสอบถูกเก็บไว้ที่ใด
• ความสามารถในการปรับขนาด: ระบบจัดการกับปริมาณการอัปโหลดที่เพิ่มขึ้นอย่างไร ขีดจํากัดความจุของพื้นที่จัดเก็บข้อมูลคืออะไร
• ความสามารถในการบํารุงรักษา: ไฟล์ที่อัปโหลดจะถูกล้างอย่างไรเมื่อพนักงานออกจากองค์กร
• การช่วยสําหรับการเข้าถึง: UI การอัปโหลดเป็นไปตามมาตรฐาน Web Content Accessibility Guidelines (WCAG) 2.1 AA หรือไม่

หากแผนละเว้นข้อควรพิจารณาเหล่านี้ ให้เพิ่มข้อควรพิจารณาเหล่านั้นอย่างชัดเจน ข้อกําหนดที่ไม่ทํางานมักจะกลายเป็นความคิดหลังการนําไปใช้หากไม่ได้รับการแก้ไขในการวางแผน

ประเมินความเป็นไปได้และความสมบูรณ์

ประเมินว่าแผนให้คําแนะนําที่เพียงพอสําหรับการนําไปใช้หรือไม่ แผนที่คลุมเครือเกินไป ("ใช้การอัปโหลดไฟล์") จะไม่เป็นประโยชน์ แผนที่กําหนดไว้มากเกินไป ("ใช้โค้ด 47 บรรทัดพอดี") มีข้อจํากัดมากเกินไป

ระดับรายละเอียดที่เหมาะสมให้ทิศทางที่ชัดเจนโดยไม่ลบความยืดหยุ่นทั้งหมด แผนควรตอบ:

• ส่วนประกอบใดที่ต้องสร้างหรือแก้ไข
• ส่วนประกอบเหล่านี้มีปฏิสัมพันธ์อย่างไร
• ใช้เทคโนโลยีและไลบรารีอะไรบ้าง
• ลําดับการดําเนินการคืออะไร?
• ขั้นตอนการยืนยันใดที่รับรองความถูกต้อง

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

ระบุองค์ประกอบที่ขาดหายไป

มองหาช่องว่างในแผน การละเว้นทั่วไป ได้แก่ :

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

แก้ไขช่องว่างเหล่านี้โดยการแก้ไข plan.md ด้วยตนเองหรือให้บริบทเพิ่มเติมและสร้างส่วนที่เกี่ยวข้องใหม่

สร้างใหม่ด้วยบริบทที่ละเอียด

หากแผนเริ่มต้นพลาดเป้า ให้ระบุบริบทที่เฉพาะเจาะจงมากขึ้นและสร้างใหม่ ตัวอย่างเช่น หากแผนแนะนําให้ใช้ฐานข้อมูลใหม่ แต่คุณจําเป็นต้องใช้ฐานข้อมูลที่มีอยู่ ให้ชี้แจง: "ใช้ฐานข้อมูล EmployeePortal ที่มีอยู่ เพิ่มตาราง DocumentMetadata ลงในฐานข้อมูลนี้แทนที่จะสร้างตารางใหม่"

สร้างแผนใหม่ด้วยการ /speckit.plan รวมบริบทที่อัปเดตนี้ AI จะปรับแนวทางให้เหมาะสม

แก้ไขแผนด้วยตนเอง

เนื่องจาก plan.md เป็นไฟล์ Markdown คุณจึงสามารถแก้ไขได้โดยตรง หาก AI แนะนําแนวทางที่ถูกต้อง 90% แต่ต้องการการปรับเปลี่ยนเล็กน้อย ให้แก้ไขไฟล์แทนที่จะสร้างทุกอย่างใหม่

ตัวอย่างเช่น ถ้าแผนเสนอชื่อคอนเทนเนอร์ Blob เฉพาะ แต่องค์กรของคุณมีแบบแผนการตั้งชื่อ ให้อัปเดตชื่อคอนเทนเนอร์ใน plan.md โดยตรง

ทํางานร่วมกับสมาชิกในทีม

ในสภาพแวดล้อมของทีม ให้แชร์ plan.md เพื่อตรวจสอบ นักพัฒนาหรือสถาปนิกอาวุโสสามารถตรวจสอบการตัดสินใจทางสถาปัตยกรรมก่อนเริ่มการใช้งาน การตรวจสอบโดยผู้เชี่ยวชาญนี้จะตรวจจับปัญหาที่การตรวจสอบอัตโนมัติอาจพลาดไป

การตรวจสอบทีมยังสร้างความเข้าใจร่วมกัน เมื่อนักพัฒนาหลายคนทํางานกับคุณลักษณะ การทบทวนแผนร่วมกันจะช่วยให้มั่นใจได้ว่าทุกคนรู้แนวทางและสามารถระบุความขัดแย้งที่อาจเกิดขึ้นกับงานอื่นๆ ที่กําลังดําเนินอยู่ได้

จัดทําเอกสารการตัดสินใจด้านสถาปัตยกรรม

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

พิจารณาทางเลือกในการบันทึก

เมื่อคุณเลือกระหว่างวิธีการที่ใช้งานได้หลายวิธี ให้บันทึกทางเลือกที่คุณพิจารณาและเหตุผลที่คุณเลือกวิธีใดวิธีหนึ่งมากกว่าวิธีอื่น

สําหรับการจัดเก็บแฟ้ม คุณอาจพิจารณาสามวิธี:

• ที่เก็บข้อมูล Azure Blob: เลือกเพื่อความคุ้มค่า ความสามารถในการปรับขนาด และการรวมเข้ากับสภาพแวดล้อม Azure ที่มีอยู่
• ไฟล์ Azure: ถูกปฏิเสธเนื่องจากค่าใช้จ่ายที่สูงขึ้นสําหรับการจัดเก็บไฟล์ขนาดใหญ่และค่าใช้จ่ายของโปรโตคอล Server Message Block (SMB) ที่ไม่จําเป็น
• SQL Database FILESTREAM: ถูกปฏิเสธเพื่อหลีกเลี่ยงการเพิ่มขนาดและความซับซ้อนของฐานข้อมูล

เอกสารนี้ป้องกันไม่ให้นักพัฒนาในอนาคตตั้งคําถามว่าเหตุใดจึงไม่ใช้วิธีการที่ง่ายกว่า เหตุผลในการตัดสินใจจะถูกเก็บรักษาไว้แทนที่จะสูญหายไปตามกาลเวลา

บันทึกสมมติฐาน

แผนตั้งสมมติฐานเกี่ยวกับระบบ โครงสร้างพื้นฐาน และข้อจํากัดขององค์กรที่มีอยู่ ทําให้สมมติฐานเหล่านี้ชัดเจน

ตัวอย่างสมมติฐานสําหรับการอัปโหลดเอกสาร:

• คอนเทนเนอร์ employee-documents Azure Blob Storage ถูกจัดเตรียมโดยทีมโครงสร้างพื้นฐานก่อนเริ่มการพัฒนา
• การรับรองความถูกต้องของพอร์ทัลที่มีอยู่ให้โทเค็น Microsoft Entra ID ที่ผ่านการตรวจสอบแล้วซึ่งสามารถเชื่อถือได้สําหรับการระบุตัวตนของผู้ใช้
• ฐานข้อมูล SQL มีความจุเพียงพอสําหรับตารางข้อมูลเมตาอื่นโดยไม่ต้องขยายที่เก็บข้อมูล
• โครงสร้างพื้นฐานเครือข่ายรองรับการอัปโหลด HTTP ขนาด 50 MB โดยไม่มีข้อจํากัดของพร็อกซีหรือไฟร์วอลล์

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

วางแผนสําหรับวิวัฒนาการในอนาคต

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

สําหรับการอัปโหลดเอกสารข้อกําหนดในอนาคตอาจรวมถึง:

• รองรับไฟล์ประเภทอื่นนอกเหนือจาก PDF และ DOCX
• การใช้การแชร์ไฟล์ระหว่างพนักงาน
• การเพิ่มการกําหนดเวอร์ชันเอกสาร
• การเปิดใช้งานการอัปโหลดไฟล์หลายไฟล์จํานวนมาก
• การผสานรวมการสแกนไวรัส

หากสถาปัตยกรรมของคุณทําให้ส่วนขยายเหล่านี้ทําได้ยาก ให้พิจารณาว่าควรปรับการออกแบบเริ่มต้นหรือไม่ คุณไม่ได้ใช้คุณสมบัติในอนาคตในตอนนี้ แต่คุณหลีกเลี่ยงการวาดภาพตัวเองให้อยู่ในมุมที่ทําให้การเปลี่ยนแปลงในอนาคตเจ็บปวด

แบ่งปันและรักษาแผนระหว่างการดําเนินการ

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

แบ่งปันแผนกับผู้มีส่วนได้ส่วนเสีย

หลังจากสรุปแผนแล้ว ให้แบ่งปันกับผู้มีส่วนได้ส่วนเสียที่เกี่ยวข้องเพื่อตรวจสอบความถูกต้อง:

• ผู้จัดการผลิตภัณฑ์: ตรวจสอบว่าแผนส่งมอบข้อกําหนดข้อมูลจําเพาะทั้งหมด
• ทีมรักษาความปลอดภัย: ยืนยันว่าการควบคุมความปลอดภัยเป็นไปตามมาตรฐานขององค์กร
• ทีมโครงสร้างพื้นฐาน: ตรวจสอบให้แน่ใจว่าทรัพยากร Azure ที่เสนอสามารถเตรียมใช้งานและกําหนดค่าได้
• ทีมสถาปัตยกรรม: ตรวจสอบความสอดคล้องกับหลักการสถาปัตยกรรมองค์กร

การตรวจสอบผู้มีส่วนได้ส่วนเสียนี้จะจับปัญหาก่อนเริ่มดําเนินการ ถ้าคําติชมของทีมรักษาความปลอดภัยเผยให้เห็นว่าการรับรองความถูกต้องที่เสนอไม่เพียงพอ ให้อัปเดตแผนก่อนที่จะเขียนโค้ด

อัปเดตแผนตามต้องการ

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

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

ให้ plan.md ซิงโครไนซ์กับการใช้งานจริง เมื่อแผนและรหัสแตกต่าง แผนจะสูญเสียมูลค่าเป็นเอกสารอ้างอิง

• แนวทางการรักษาความปลอดภัยตรงตามข้อกําหนดขององค์กรหรือไม่
• การออกแบบ Schema ฐานข้อมูลเป็นไปตามแบบแผนการตั้งชื่อหรือไม่

หากแผนแนะนําให้ใช้ฐานข้อมูล แต่พอร์ทัลที่มีอยู่ของคุณมีอยู่แล้ว นั่นอาจเกินความจําเป็น หากแผนเสนอเทคโนโลยีที่ทีมของคุณหลีกเลี่ยง ให้บันทึกเหตุผลหรือปรับแผน

ข้อผิดพลาดทั่วไปในการวางแผนที่ควรหลีกเลี่ยง

หลีกเลี่ยงข้อผิดพลาดทั่วไปเหล่านี้เมื่อสร้างและตรวจสอบแผน:

• ข้ามขั้นตอนการวางแผน: การข้ามจากข้อกําหนดไปยังโค้ดโดยตรงโดยไม่มีแผนจะเพิ่มความเสี่ยงที่จะเกิดข้อผิดพลาดทางสถาปัตยกรรม เวลาที่ลงทุนในการวางแผนจ่ายเงินปันผลโดยป้องกันการทําซ้ํา

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

• การนําไปใช้อย่างจํากัดมากเกินไป: แผนควรเป็นแนวทาง ไม่ใช่กําหนดทุกรายละเอียด เว้นที่ว่างให้นักพัฒนาตัดสินใจทางยุทธวิธีที่เหมาะสมระหว่างการใช้งาน

• เพิกเฉยต่อความขัดแย้งของรัฐธรรมนูญ: หากแผนละเมิดหลักการของรัฐธรรมนูญ ให้จัดการกับความขัดแย้งทันที ปรับแผนให้สอดคล้องกับหรือปรับปรุงรัฐธรรมนูญหากจําเป็นต้องแก้ไขหลักการ

• ลืมอัปเดตแผน: เมื่อการใช้งานเปิดเผยข้อมูลใหม่ ให้อัปเดต plan.md แผนเก่าทําให้นักพัฒนาในอนาคตเข้าใจผิดและลดมูลค่าของเอกสารของคุณ

Summary

แผนทางเทคนิคจะเปลี่ยนข้อมูลจําเพาะของคุณให้เป็นสถาปัตยกรรมที่นําไปใช้ได้จริง สร้างแผนโดยใช้ /speckit.plan บริบทที่เหมาะสมเกี่ยวกับสแต็กเทคโนโลยีและโครงสร้างพื้นฐานของคุณ ทบทวนแผนอย่างมีวิจารณญาณเพื่อให้แน่ใจว่าครอบคลุมข้อกําหนดข้อกําหนดทั้งหมด สอดคล้องกับรัฐธรรมนูญของคุณ และให้คําแนะนําในการนําไปใช้อย่างเพียงพอ ใช้แผนที่ตรวจสอบแล้วเพื่อเป็นแนวทางในการสร้างและการใช้งานงาน ปฏิบัติต่อ plan.md เป็นเอกสารที่มีชีวิตที่พัฒนาไปพร้อมกับความเข้าใจของคุณและให้บริบทที่มีคุณค่าสําหรับวงจรชีวิตการพัฒนาทั้งหมด