จาก Requirements สู่ Code: เวิร์กโฟลว์ AI Agent ที่ตรวจสอบย้อนกลับได้

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

บทช่วยสอนนี้ตั้งใจสร้างบันทึกนั้นขึ้นมา นั่นคือห่วงโซ่เส้นเดียวจากข้อกำหนดที่เขียนไว้ไปจนถึง pull request ที่ merge แล้ว โดยทุกจุดเชื่อมต่อเป็นสิ่งที่คุณเปิดดูได้จริง Spec Kit ของ GitHub แก้ช่องว่างเดียวกันนี้ด้วยไฟล์ในรีโพซิทอรี ส่วนไกด์นี้แก้ด้วยระบบการทำงาน โดยใช้ Sharkly เพราะมันเก็บทั้งห่วงโซ่ไว้บน Task เดียว แม้ว่ารูปแบบนี้จะย้ายไปใช้กับ tracker ตัวไหนก็ได้ที่เก็บลิงก์แบบเดียวกันได้ ถ้าคุณอยากเห็นวงจรการทำงานก่อน เริ่มจากไกด์เรื่องการบริหารจัดการโปรเจกต์ด้วย AI agentของเรา

สรุปสั้น ๆ

เวิร์กโฟลว์แบบ requirements-to-code ที่ตรวจสอบย้อนกลับได้ คือเวิร์กโฟลว์ที่ทุกอาร์ติแฟกต์ชี้กลับไปยังอาร์ติแฟกต์ที่ทำให้มันเกิดขึ้น ได้แก่ ข้อกำหนด, Task, sub-task, การรัน, pull request และการรับงาน ใน Sharkly ข้อกำหนดจะกลายเป็น Task หนึ่งอัน เอเจนต์เสนอการแตกงานใน Plan mode แล้วมีคนยืนยัน sub-task แต่ละอันรันใน worktree ที่แยกออกมาต่างหากพร้อม execution log ส่วน pull request เชื่อมกลับมาด้วย Task ID และมีคนกดรับผลลัพธ์เทียบกับเกณฑ์การยอมรับที่เขียนไว้ตั้งแต่ต้น เอเจนต์ค้นคว้า ลงมือทำ ทดสอบ และรายงานผล คนเป็นคนกำหนดทิศทาง มอบอำนาจ และรับผลลัพธ์

คำว่า traceable ต้องหมายถึงอะไร

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

ถ้าจุดเชื่อมไหนหายไป ห่วงโซ่นี้ก็เป็นแค่ของประดับ ช่องโหว่ที่พบบ่อยที่สุดคือจุดสุดท้าย นั่นคือ pull request ที่ merge แล้วถูกนับเป็นการรับงานทั้งที่ไม่มีใครเอาการเปลี่ยนแปลงไปเทียบกับข้อกำหนดเลย

ขั้นที่ 1: เขียนข้อกำหนดเป็น Task

Task คือหน่วยพื้นฐานของงานที่ติดตามได้ใน Sharkly และ Space ที่ตั้งค่าสำหรับพัฒนาซอฟต์แวร์จะมีชนิดงานเริ่มต้นคือ Requirement, Bug, Task และ User Story ใช้ Requirement หรือ User Story เป็น Task แม่ ชนิดงานเป็นตัวกำหนดว่าจะใช้ custom field ตัวไหนและใช้สถานะ Workflow ชุดไหน ดังนั้น Requirement จึงมีสถานะตรวจทานของตัวเองได้โดยไม่ไปปนกับเวิร์กโฟลว์ของ Bug

น้ำหนักทั้งหมดอยู่ที่คำอธิบาย เขียนให้คนที่ไม่เคยเห็นบทสนทนามาก่อนอ่านรู้เรื่อง ว่าทำไมงานนี้ถึงสำคัญ อะไรอยู่ในขอบเขตและอะไรไม่อยู่ ไฟล์ที่เกี่ยวข้องหรือพฤติกรรมที่สังเกตได้ การตัดสินใจที่ตกลงกันไปแล้ว และจะตรวจสอบความสำเร็จอย่างไร บรรทัดสุดท้ายนั่นแหละคือเกณฑ์การยอมรับ ซึ่งเป็นหลักยึดของจุดเชื่อมที่หก ถ้าคุณยังเขียนมันไม่ได้ แปลว่าข้อกำหนดยังไม่พร้อม และ Backlog ก็มีไว้เพื่อกรณีนี้โดยเฉพาะ Task ที่มอบหมายให้เอเจนต์จะไม่เริ่มทำงานตราบใดที่ยังอยู่ใน Backlog

ผูก repository ไว้ที่ระดับ Space เพื่อให้ทุก sub-task สืบทอดไปด้วย เอเจนต์ที่ไม่มีการผูก repository จะถอยไปใช้ Git repository ของ Space ซึ่งเป็นสิ่งที่คุณต้องการสำหรับฟีเจอร์ที่มีหลาย Task

ขั้นที่ 2: ให้เอเจนต์ร่างการแตกงาน แล้วค่อยยืนยัน

เปิดแชตเอเจนต์ของ Task แล้วสลับเซสชันไปที่ Plan mode ใน Plan mode เอเจนต์สามารถเสนอการกระทำให้คุณตรวจดูก่อน และ Sharkly จะสร้าง Task กับ sub-task ที่วางแผนไว้หลังจากคุณยืนยันข้อเสนอแล้วเท่านั้น คุณจะยืนยันโดยยังไม่เริ่มงาน หรือยืนยันแล้วเริ่มงานไปเลยก็ได้

นี่คือจุดเชื่อมที่ทีมส่วนใหญ่ข้ามไป และมันคือสิ่งที่ทำให้การแตกงานตรวจสอบย้อนกลับได้ แทนที่จะเป็นการคิดสด ๆ หน้างาน ข้อเสนอปรากฏให้เห็นก่อนกลายเป็นงานจริง คุณลบ sub-task ที่ขยายขอบเขตเกินไปออก เพิ่มขั้นตอน migration ที่เอเจนต์มองข้ามไปได้ sub-task จะอยู่ใน Space เดียวกับ Task แม่เสมอ และ Sharkly ปฏิเสธการตั้งตัวเองเป็นแม่และวงจรวนซ้ำ โครงสร้างลำดับชั้นจึงยังเป็นต้นไม้เสมอ

ใช้เอเจนต์เดียวสำหรับข้อกำหนดที่บทบาทเดียวรับมือไหว ใช้ Crew เมื่อหัวหน้าทีมต้องตีความเป้าหมาย ดึงสมาชิกเอเจนต์คนอื่นอย่างคนเขียนเทสต์เข้ามาเกี่ยวข้อง แล้วรวบผลลัพธ์กลับเข้า Task เดียว สำหรับการแก้โค้ดสามไฟล์ การใช้ Crew เพิ่มชิ้นส่วนที่ต้องขยับโดยไม่ได้เพิ่มความสามารถในการตรวจสอบย้อนกลับ ไกด์เรื่อง Sharkly Crews ของเราอธิบายโมเดลที่หัวหน้านำทีมไว้แล้ว

คัดลอกทุกอย่างที่ตัดสินใจกันในแชตลงในคำอธิบาย Task ด้วย แชตบน Task ไม่ใช่คอมเมนต์และไม่ปรากฏใน Activity ดังนั้นการตัดสินใจที่อยู่แค่ในแชตจะมองไม่เห็นจากห่วงโซ่

ขั้นที่ 3: รันงานแบบแยกส่วน พร้อมร่องรอย

มอบหมาย sub-task แต่ละอันให้เอเจนต์ผ่านตัวควบคุม Assignee แล้วย้ายมันออกจาก Backlog Sharkly จะตรวจหมวดหมู่สถานะและความพร้อมในการรัน เข้าคิวการรัน แล้วส่งไปยัง Computer ที่เลือกไว้ ซึ่งบริการในเครื่องจะเตรียมไดเรกทอรีงานที่แยกออกมาต่างหากและสตาร์ท Runtime

มีสองรายละเอียดที่ทำให้จุดเชื่อมนี้ซื่อสัตย์ การรันจะรวมชื่อและคำอธิบายของ Task คอมเมนต์ล่าสุด และ Workflow ของชนิด Task พร้อมสถานะที่อนุญาตไว้ เอเจนต์จึงทำงานจากข้อกำหนดจริงไม่ใช่คำสรุปความ และการรันที่ผูกกับ repository แต่ละครั้งจะได้ worktree ของตัวเองในโหมด Temporary ดังนั้น sub-task ที่รันขนานกันจึงเขียนทับกันไม่ได้ บทความของเราเรื่องการรันเอเจนต์ขนานกันโดยไม่เกิด merge conflictอธิบายว่าทำไมการแยกส่วนจึงทำให้การกระจายงานออกขนานกันปลอดภัย

ความคืบหน้า เหตุการณ์ในร่องรอย และผลลัพธ์จะส่งกลับเข้า Task execution log บันทึกว่าทำไมการรันจึงถูกเข้าคิว เริ่มและจบเมื่อไร การเรียกใช้เครื่องมือและเหตุการณ์ของ Runtime แหล่งที่มาของ trigger และรายละเอียดความล้มเหลว บันทึกนั่นแหละคือจุดเชื่อมที่สี่

ขั้นที่ 4: เชื่อม pull request ด้วย ID

เชื่อมต่อองค์กร GitHub ครั้งเดียว แล้วใส่ Task ID ลงในชื่อเรื่องของ pull request คำอธิบาย หรือชื่อแบรนช์ต้นทาง ทั้ง SH-312 เดี่ยว ๆ และ Fixes SH-312 ต่างก็สร้างลิงก์ได้ ส่วน linkback จะคอมเมนต์ URL ของ Task ไว้บน pull request ซึ่งเปิดใช้เป็นค่าเริ่มต้นสำหรับ repository แบบส่วนตัว

ทีนี้มาดูเส้นแบ่ง เพราะมันสำคัญต่อการตรวจสอบย้อนกลับ คำอย่าง fixes และ closes ไม่ได้มีความหมายเพิ่มอะไร และการ merge pull request ก็ไม่ได้เปลี่ยนสถานะของ Task Sharkly เชื่อมการเปลี่ยนแปลงเข้ากับ Task แต่ไม่ได้ตัดสินว่า Task เสร็จแล้ว สถานะยังคงเป็นการตัดสินใจของคน ซึ่งนั่นคือหัวใจของจุดเชื่อมที่หก บทความแนะนำขั้นตอนการมอบหมายตั๋ว Jira ให้ AI agent แล้วได้ PR กลับมาของเราแสดงลิงก์แบบเดียวกันนี้จากฝั่ง tracker

ขั้นที่ 5: ตรวจทานเทียบกับข้อกำหนด แล้วจึงรับงาน

เอเจนต์สามารถปล่อยให้ Task รอการตรวจทานจากคนได้ และสัญญาณนั้นจะไปโผล่ใน Inbox ของผู้รับผิดชอบใต้หมวด Primary อ่านสามอย่างตามลำดับ เกณฑ์การยอมรับจากขั้นที่หนึ่ง คอมเมนต์ของเอเจนต์ที่ไล่รายการการตรวจสอบที่รันไปและสิ่งที่ยังไม่แน่ใจ และ execution log จากนั้นค่อยดู diff

ถ้ามี Task ทดสอบแยกต่างหากที่ตรวจสอบการเปลี่ยนแปลงนี้ ให้บันทึกความสัมพันธ์นั้นอย่างชัดเจน Organization Owner และ Admin สร้างชนิดลิงก์กำหนดเองได้ และตัวอย่างในเอกสารเอง คือ validates / is validated by ก็คือเส้นเชื่อมการตรวจสอบย้อนกลับของจุดเชื่อมนี้ ความสัมพันธ์ไม่เปลี่ยนสถานะด้วยตัวเอง ดังนั้นการรับงานยังต้องเป็นการเปลี่ยนสถานะที่คนเป็นคนทำ

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

จุดที่ห่วงโซ่ขาด

เวิร์กโฟลว์ข้างต้นมีจุดที่ห่วงโซ่ขาดได้สามจุดที่รู้กันอยู่ และควรพูดให้ตรง ๆ

ข้อสรุปที่ค้างอยู่ในแชต เซสชัน Agent Chat แบบเดี่ยวเป็นของคนที่สร้างมันขึ้นมา ถ้าตกลงแบบกันในนั้นเสร็จ Task ก็ไม่รู้เรื่อง

การรันที่เริ่มนอก Task การกระทำ Run Agent ของเวิร์กโฟลว์อัตโนมัติไม่ได้สร้าง Task การรันจะถูกบันทึกไว้ที่เอเจนต์ ซึ่งโอเคสำหรับการตรวจสอบตอนกลางคืน แต่ผิดสำหรับงานฟีเจอร์

ใช้ไฟล์แทนบันทึก ไฟล์ spec.md, plan.md และ tasks.md ของ Spec Kit เป็นห่วงโซ่ที่แข็งแรงสำหรับนักพัฒนาคนเดียวที่ทำงานในรีโพซิทอรีเดียว ใช้มันเมื่อทั้งทีมคือตัวคุณเอง และใช้ระบบการทำงานที่แชร์ร่วมกันเมื่อมีคนที่สองที่ต้องตรวจทาน รับงาน หรือถามว่าเกิดอะไรขึ้นโดยไม่ต้องเปิด checkout ของคุณ Sharkly ไม่ใช่ตัวแทนของ Claude Code, Codex หรือเครื่องมือรันงานอื่น ๆ แต่มันคือชั้นที่ทำให้ห่วงโซ่ยังมองเห็นได้รอบ ๆ เครื่องมือเหล่านั้น เอกสารอธิบายแต่ละแนวคิดไว้ลึกกว่านี้ที่ docs.sharkly.ai

คำถามที่พบบ่อย

requirements to code หมายความว่าเอเจนต์เป็นคนเขียนข้อกำหนดหรือเปล่า? ไม่ใช่ คนเป็นคนเขียนข้อกำหนดและเกณฑ์การยอมรับของมัน เอเจนต์ค้นคว้าโค้ดเบสและเสนอการแตกงานใน Plan mode ได้ แต่ข้อเสนอจะกลายเป็น Task ก็ต่อเมื่อมีคนยืนยันแล้วเท่านั้น

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

ถ้า pull request ถูก merge ก่อนการตรวจทานล่ะ? สถานะของ Task จะไม่เปลี่ยน ห่วงโซ่จึงแสดง Task ที่ยังไม่ถูกรับงานทั้งที่มีการเปลี่ยนแปลง merge แล้ว ซึ่งเป็นสัญญาณที่ถูกต้อง เพราะยังมีคนติดค้างการตัดสินใจอยู่

ฟีเจอร์ที่ตรวจสอบย้อนกลับได้ตัวแรกควรเล็กแค่ไหน? ข้อกำหนดหนึ่งข้อ sub-task สองหรือสามอัน เอเจนต์หนึ่งตัว บทความแนะนำขั้นตอนการบริหารจัดการโปรเจกต์ด้วย Claude Codeของเรารันวงจรนี้ครบทั้งวงบน Task เดียว