บล็อก Maguyva

บริบทที่เดินทางไปกับคุณ

Mon, 07 Sep 2026 00:00:00 GMT

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

บทความนี้พูดถึงอีกครึ่งหนึ่งของสัปดาห์ทั่วไป รีโพซิทอรีเดียวกันนั้นก็เปิดอยู่ใน Claude Code เช่นกัน ถูกสอบถามจาก Codex CLI ถูกตรวจสอบบนเครื่องที่สอง หรือถูกสอบถามโดยเอเจนต์ที่รันใน CI คำถามไม่ใช่ ‘ตัวสร้างดัชนีตัวไหนดีกว่า’ คำถามคือแผนที่ที่เอเจนต์เชื่อถือในหน้าต่างหนึ่งนั้นเป็นแผนที่เดียวกันกับที่มันเชื่อถือในหน้าต่างถัดไปหรือไม่

Maguyva คือแผนที่ที่เดินทางไปกับคุณ มันคือชั้นบริบทโค้ดเบส MCP ระยะไกล เอเจนต์สอบถามมันในลักษณะเดียวกับที่สอบถามเครื่องมือ MCP อื่น ๆ ผลลัพธ์กลับมาเป็นเส้นทางไฟล์ที่จัดอันดับแล้วพร้อมหมายเลขบรรทัด Cursor ยังคงเป็นตัวแก้ไขโค้ด บริบทต่างหากที่เคลื่อนที่

ตัวสร้างดัชนีของ Cursor มีไว้เพื่ออะไร

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

นี่คือวิธีการทำงาน ตามที่อธิบายไว้ในเอกสารสาธารณะของ Cursor และคำอธิบายของ Cursor เอง ณ เวลาที่เขียนบทความนี้: เส้นทางการค้นหาหลักไม่ใช่ดัชนี embedding บนคลาวด์อีกต่อไป ทีม Cursor ระบุในฟอรัมชุมชนของพวกเขาว่าการค้นหาเชิงความหมายด้วย embedding เฉพาะทางกำลังถูกลดบทบาทลง เพื่อหันไปใช้การดึงข้อมูลแบบ grep เนื่องจากโมเดลปัจจุบันเก่งพอที่จะสำรวจต้นไม้ไฟล์ปัจจุบันด้วยตัวเองอยู่แล้ว แทนที่ด้วย Instant Grep ซึ่งเป็นดัชนีค้นหาในเครื่องที่สร้างจาก n-gram, รายการดัชนีผกผัน และตัวกรอง Bloom จัดเก็บในตารางค้นหาที่แมปเข้าหน่วยความจำ เพื่อให้คิวรีถูกประมวลผลบนเครื่องของนักพัฒนาเองแทนที่จะเป็นเซิร์ฟเวอร์

ดัชนีเองอาศัยอยู่ในไดเรกทอรี .git/cursor/ ของรีโพซิทอรีเอง ยึดกับ git commit เฉพาะ การเปลี่ยนแปลงตั้งแต่ commit นั้นจะถูกซ้อนทับแทนที่จะกระตุ้นการสแกนใหม่ และดัชนีจะถูกสร้างใหม่ก็ต่อเมื่อสถานะในเครื่องเบี่ยงเบนไปมากจากสิ่งที่มันสร้างขึ้นบน เนื่องจากมันอยู่ใน .git มันไม่เคยถูกติดตามและไม่เคยถูกพุชขึ้นรีโมต — ลบโฟลเดอร์นั้น แล้วดัชนีก็หายไป .gitignore ได้รับการเคารพในการสร้าง เนื่องจากมีเพียงเนื้อหาที่ถูกติดตามเท่านั้นที่มีสิทธิ์ และ .cursorignore ถูกบังคับใช้ในเส้นทางการอ่าน ไม่มีขั้นตอน embedding ฝั่งเซิร์ฟเวอร์หรือฐานข้อมูลเวกเตอร์ระยะไกลในเส้นทางนั้นอีกต่อไป เอกสารเก่าเคยอธิบายการออกแบบที่ช่วยเหลือด้วยคลาวด์ — การเข้ารหัสชิ้นส่วนโค้ด, การซิงค์ผ่านต้นไม้ Merkle, การใช้ดัชนีร่วมกันระหว่างสมาชิกในทีม — และทีม Cursor เองก็กล่าวตั้งแต่นั้นมาว่าการออกแบบนั้นกำลังถูกลดบทบาทลง ดังนั้นบทความนี้จึงไม่อธิบายมันว่าเป็นปัจจุบันอีกต่อไป

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

พื้นที่ทำงานแบบหลายรูทได้รับการรองรับ: บริบทของแต่ละโฟลเดอร์ที่เปิดอยู่จะพร้อมใช้งานสำหรับ Agent คุณสมบัติบางอย่างที่พึ่งพา git เช่น worktree จะถูกปิดใช้งานในการตั้งค่าแบบหลายรูท และ Cloud Agents ไม่รองรับพื้นที่ทำงานแบบหลายรูทเลย

ไม่มีสิ่งใดในนี้ที่เป็นเหตุผลให้เลิกใช้ Cursor มันคือคำอธิบายที่ถูกต้องของแผนที่ที่ดีมากในที่ที่มันอาศัยอยู่

‘เดินทางไปกับคุณ’ หมายความว่าอย่างไรกันแน่

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

ใน Cursor: ‘parseConfig ถูกกำหนดที่ไหน และใครเรียกใช้มัน’
ใน Claude Code บนรีโพเดียวกัน: คำถามเดียวกัน
ใน Codex CLI บนเครื่องตรวจสอบที่ไม่เคยเปิดหน้าต่าง Cursor เลย: คำถามเดียวกัน
ในเอเจนต์ CI ที่พูดภาษา MCP: คำถามเดียวกัน กับสแนปช็อตบนคลาวด์เดียวกัน

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

ตัวสร้างดัชนีของ Cursor ไม่ได้ถูกออกแบบมาเพื่อแก้ปัญหานั้น เนื่องจากมันอาศัยอยู่ภายในตัวแก้ไขโค้ด บริบทที่มันสร้างจึงมีไว้สำหรับตัวแก้ไขโค้ดนั้น ผู้อ่านที่ต้องการ CLI, ไปป์ไลน์ CI หรือตัวแก้ไขโค้ดอื่นด้วยเช่นกัน จำเป็นต้องมีเครื่องมือแยกต่างหากสำหรับพื้นผิวเหล่านั้น นี่คือข้อเท็จจริงเรื่องขอบเขต ไม่ใช่ข้อบกพร่อง Maguyva คือเครื่องมือแยกต่างหากนั้น

จำนวนภาษาที่เผยแพร่สำหรับตัวสร้างดัชนีของ Cursor ไม่ได้ถูกระบุไว้ในเนื้อหาที่ใช้งานได้ของบทความนี้ Maguyva เผยแพร่การรองรับมากกว่า 279 ภาษาและเทคโนโลยีที่อิงข้อความ ราคาของ Cursor ก็ไม่ได้ถูกทำซ้ำที่นี่เช่นกัน ดูหน้าราคาของพวกเขา Maguyva คิดค่าบริการต่อพื้นที่ทำงาน ไม่ใช่ต่อที่นั่ง โดยมีแผนที่เผยแพร่ที่ $0, $19, $49 และ $149 ขึ้นอยู่กับความครอบคลุมที่จัดทำดัชนีและขนาดพื้นที่ทำงาน

แผนที่บนคลาวด์เดียว ทุกไคลเอนต์ MCP

Maguyva คือเซิร์ฟเวอร์ MCP ระยะไกล คุณเชื่อมต่อ GitHub เลือกรีโพซิทอรีและไปป์ไลน์บนคลาวด์จะสร้างสัญลักษณ์ ขอบกราฟ และแผนที่ที่จัดอันดับแล้ว คุณเพิ่มคีย์ API ในการตั้งค่า MCP ของไคลเอนต์ที่คุณใช้อยู่แล้ว Maguyva มีคู่มือการตั้งค่าสำหรับไคลเอนต์ MCP ที่มีเอกสารประกอบ 24 ตัว — รวมถึง Cursor — และสามารถเชื่อมต่อกับไคลเอนต์ที่เข้ากันได้กับ MCP อื่น ๆ ที่รองรับการตั้งค่ามาตรฐานได้

หน้าการตั้งค่า Cursor เป็นเส้นทางเฉพาะสำหรับตัวแก้ไขโค้ด หากนั่นคือที่ที่คุณทำงาน เซิร์ฟเวอร์เดียวกันตอบสนอง Claude Code, VS Code, Windsurf, Codex CLI และอื่น ๆ คุณไม่ได้เปลี่ยนตัวแก้ไขโค้ด คุณกำลังมอบพื้นผิวเครื่องมือเดียวกันให้กับทุกเอเจนต์: เครื่องมือ MCP ที่เน้นลูกค้า 11 ตัวครอบคลุมการค้นหา สัญลักษณ์ การวิเคราะห์การพึ่งพา การดึงไฟล์ บริบทรีโพซิทอรีและเวิร์กโฟลว์เครื่องมืออรรถประโยชน์ที่กำหนดผลลัพธ์ได้แน่นอน การค้นหาเชิงความหมาย เชิงโครงสร้าง เชิงกราฟ และข้อความรวมกันเป็นผลลัพธ์ที่มีการจัดอันดับ

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

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

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

แผนที่ทั้งสองอยู่ร่วมกันอย่างไร

ใช้ทั้งสองอย่าง มันไม่ใช่ทางเลือกในความหมายของหน้าเปรียบเทียบ

เปิดตัวสร้างดัชนีของ Cursor ไว้สำหรับโปรเจกต์บนดิสก์ ให้ Explore, Instant Grep และเอเจนต์ภายในตัวแก้ไขโค้ดใช้มัน วงจรนั้นเป็นแบบเนทีฟและรวดเร็ว
เพิ่ม Maguyva เป็นเซิร์ฟเวอร์ MCP ใน Cursor เพื่อให้เซสชันเดียวกันสามารถสอบถามแผนที่พื้นที่ทำงานบนคลาวด์ได้ด้วย Cursor เป็นไคลเอนต์ Maguyva ที่มีเอกสารประกอบ คุณไม่ได้เลือกดัชนีหนึ่งแล้วลบอีกดัชนีหนึ่ง
เพิ่มเซิร์ฟเวอร์ Maguyva ตัวเดียวกันไปยัง Claude Code, Codex CLI หรือไคลเอนต์ MCP อื่นใดที่แตะต้องรีโพ รูปแบบคีย์ API เดียว พื้นที่ทำงานเดียว
หากเอเจนต์ CI เข้ากันได้กับ MCP ให้ชี้ไปที่เซิร์ฟเวอร์เดียวกัน มันจะอ่านสแนปช็อตที่มีการประทับเวลาเดียวกับที่แล็ปท็อปอ่าน

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

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

สิ่งที่หน้านี้ไม่ได้อ้าง

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

มันไม่ได้อ้างว่า Maguyva แทนที่ Instant Grep หรือเอเจนต์ย่อย Explore สิ่งเหล่านั้นคือคุณสมบัติของ Cursor มันยังคงอยู่ใน Cursor

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

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

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

// same map, wherever you opened it.

แผนที่ก่อน ตรวจสอบทีหลัง

Mon, 07 Sep 2026 00:00:00 GMT

งานที่แตกต่างกันสองอย่างอยู่ในสองด้านของ pull request ก่อนที่เอเจนต์จะเขียน มันต้องการแผนที่ของต้นไม้ที่มันกำลังจะเปลี่ยนแปลง หลังจากที่เอเจนต์เปิด PR แล้ว บางสิ่งต้องอ่านการเปลี่ยนแปลงนั้นเทียบกับระบบที่เหลือ และทิ้งความคิดเห็นที่มนุษย์สามารถนำไปปฏิบัติได้

งานเหล่านี้ดูคล้ายกันจากระยะไกลเพราะทั้งคู่เกี่ยวข้องกับ ‘การเข้าใจโค้ดเบส’ มันไม่ใช่ผลิตภัณฑ์เดียวกัน อย่างหนึ่งตอบว่า ‘การเปลี่ยนแปลงนี้ควรลงจอดที่ไหน?’ อีกอย่างตอบว่า ‘อะไรที่ diff นี้ทำพังที่ลินเตอร์แบบบรรทัดต่อบรรทัดจะพลาดไป?’ การผสมทั้งสองเข้าด้วยกันให้ผลเป็นร่างแรกที่แย่กว่าและการตรวจสอบที่มีเสียงรบกวนมากกว่า

บทความนี้คือคู่มือเวิร์กโฟลว์แบบคู่ Maguyva คือแผนที่ที่เอเจนต์สอบถามก่อน Greptile คือเอเจนต์ตรวจสอบที่แสดงความคิดเห็นบน PR หลังจากนั้น คู่นี้เสริมกันตามการออกแบบ: Maguyva ไม่ตรวจสอบ pull request และ Greptile ไม่แทนที่ชั้นบริบทที่เอเจนต์ใช้เขียนมัน

ทำไมการแบ่งแยกนี้จึงมีประโยชน์

เอเจนต์เขียนโค้ดที่เริ่มต้นด้วยอคติจากการฝึกฝนบวกกับไฟล์บางไฟล์ที่ถูกวางไว้ จะประดิษฐ์เส้นทางที่น่าเชื่อถือขึ้นมาและแก้ไขมัน นี่คือความล้มเหลวแบบ ‘ไฟล์ผิด’ และมันคือปัญหาการดึงข้อมูล Maguyva คือชั้นบริบทโค้ดเบส MCP ระยะไกล: การดึงข้อมูลเชิงความหมาย เชิงโครงสร้าง (AST) เชิงกราฟ/การพึ่งพา และข้อความรวมกันเป็นผลลัพธ์ที่มีการจัดอันดับ พร้อมการค้นหาสัญลักษณ์และการดึงไฟล์ คำตอบที่มีหลักฐานกลับมาเป็น path/file.ext:line เพื่อให้คุณปฏิเสธข้อผิดพลาดได้ก่อนที่ patch จะมีอยู่ สิ่งที่อ้างนั้นเรียบง่ายโดยตั้งใจ: การเปลี่ยนแปลงที่หลอนน้อยลง โมเดลยังคงเดาได้ แค่ก้าวแรกไม่ใช่การเดาอีกต่อไป

Greptile คือเอเจนต์ตรวจสอบโค้ดที่ขับเคลื่อนด้วย AI ในคำพูดของพวกเขาเอง มันตรวจสอบทุก pull request โดยอัตโนมัติด้วยความเข้าใจโค้ดเบสอย่างเต็มที่ และวางตำแหน่งตัวเองเทียบกับลินเตอร์แบบดั้งเดิมที่ตรวจสอบไฟล์แยกกันแทนที่จะเป็นระบบทั้งหมด การตั้งค่าประกอบด้วยการติดตั้งแอป GitHub หรือ GitLab และเลือกรีโพซิทอรี ไม่มีดัชนีในเครื่องที่คุณต้องรัน การโฮสต์คือ Greptile Cloud (พวกเขาระบุว่าปฏิบัติตาม SOC 2 Type II โดยมีรายงานพร้อมให้เมื่อมีการร้องขอ) โดยมีตัวเลือกโฮสต์เองสำหรับองค์กร

ขั้นตอนที่มีหมายเลขของพวกเขาเองคือ: เชื่อมต่อและสร้างกราฟการพึ่งพาของทุกฟังก์ชัน คลาส และการพึ่งพา; ในทุก pull request วิเคราะห์การเปลี่ยนแปลงโดยใช้กราฟรีโพเต็มรูปแบบนั้น และเผยแพร่ผลการค้นพบเป็นความคิดเห็น PR พร้อมการแก้ไขที่แนะนำ ภายในเวลาประมาณสามนาที; ทุกความคิดเห็นสามารถส่งต่อปัญหาไปยังเอเจนต์เขียนโค้ดที่ทีมใช้อยู่แล้ว พวกเขายังระบุว่าอ่านความคิดเห็น PR ของมนุษย์ในอดีตเมื่อเวลาผ่านไปเพื่อเรียนรู้มาตรฐานโค้ดของทีมและลดคำแนะนำที่มีเสียงรบกวน ระบบการเรียนรู้ของพวกเขา ตามที่พวกเขาระบุเอง ใช้เวลา 2-3 สัปดาห์ในการปรับตัว

นั่นคือการตรวจสอบ ไม่ใช่การร่าง จุดแข็งของ Greptile คือบริบทกราฟรีโพเต็มรูปแบบเทียบกับการเปลี่ยนแปลงที่ลงจอดแล้วใน PR ตามด้วยวงจรปิดที่ส่งผลการค้นพบไปยัง Claude Code, Codex, Conductor, Cursor หรือ Devin จุดแข็งของ Maguyva คือแผนที่ที่มีการจัดอันดับซึ่งเอเจนต์สอบถามก่อนที่การเปลี่ยนแปลงจะถูกเขียน ใช้ทั้งสองอย่าง อย่าขอให้อย่างหนึ่งทำงานของอีกอย่างหนึ่ง

ไม่มีการระบุว่ามีการผสานรวมผลิตภัณฑ์อย่างเป็นทางการระหว่าง Maguyva และ Greptile คุณก็ไม่ต้องการมันเช่นกัน Maguyva พูดคุยกับเอเจนต์ผ่าน MCP Greptile พูดคุยกับ GitHub หรือ GitLab ผ่านแอปของพวกเขาเอง พวกเขาพบกันที่ pull request ไม่มีสคริปต์เชื่อมต่อ ไม่มี cron ที่ป้อนเครื่องมือหนึ่งไปยังอีกเครื่องมือหนึ่ง คู่นี้ไม่ต้องการ bash เพราะแต่ละผลิตภัณฑ์นั่งอยู่บนพื้นผิวที่เป็นของตัวเองอยู่แล้ว

สิ่งนี้ไม่ใช่อะไร

นี่ไม่ใช่การดูถูก Greptile นี่ไม่ใช่หน้า ‘เปลี่ยนตัวตรวจสอบของคุณ’ Greptile เปิดตัวบน Hacker News เมื่อวันที่ 5 มีนาคม 2024 ในฐานะบริษัท Y Combinator W24 และกระทู้นั้นคือวิธีที่หลาย ๆ คนรู้จักผลิตภัณฑ์นี้เป็นครั้งแรก หากนั่นคือวิธีที่คุณค้นพบพวกเขา ก็ใช้พวกเขาต่อไป หน้านี้คือครึ่งหน้าที่ขาดหายไปของวงจรนั้น: ทำให้เอเจนต์อ้างอิงข้อเท็จจริงก่อน เพื่อให้ PR ที่ Greptile เห็นนั้นกำหนดเป้าหมายไปที่ไฟล์ที่ถูกต้องอยู่แล้ว

เนื้อหาการตลาดของ Greptile นำเสนอด้วยการอ้างเรื่องความเร็วในการตรวจสอบและการจับบัค ให้ถือว่านั่นเป็นการอ้างของ Greptile เอง ไม่ใช่ตัวเลขที่ได้รับการตรวจสอบอย่างเป็นอิสระ บทความนี้ไม่ได้ทำซ้ำมันเป็นข้อเท็จจริง

ความครอบคลุมด้านภาษาก็เป็นความซื่อสัตย์แบบเดียวกัน Greptile กำหนดกรอบการรองรับว่าครอบคลุมภาษาโปรแกรมทั้งหมดแทนที่จะเป็นรายการที่ระบุไว้ ตัวเลขที่แน่นอนไม่ได้ระบุไว้ Maguyva เผยแพร่การรองรับมากกว่า 279 ภาษาและเทคโนโลยีที่อิงข้อความ พร้อมการแบ่งแยกทางเทคนิค (AST ที่รองรับโดยตัวแยกวิเคราะห์ไวยากรณ์ เทียบกับข้อความเท่านั้น) บนเว็บไซต์เมื่อคำถามเป็นเรื่องทางเทคนิค นี่คือผลิตภัณฑ์ที่แตกต่างกันที่อ้างสิ่งที่แตกต่างกัน อย่าผสมมันเข้าด้วยกัน

ราคาของ Greptile ไม่ได้ระบุไว้ในเนื้อหาที่ใช้งานได้ของบทความนี้ แผนที่เสียเงินมีอยู่ ดูหน้าราคาของพวกเขา Maguyva คิดค่าบริการต่อพื้นที่ทำงาน ไม่ใช่ต่อที่นั่ง แผนเริ่มต้นฟรี หน้าราคา แสดงรายการระดับที่เผยแพร่หากคุณต้องการตัวเลขพื้นที่ทำงาน

เวิร์กโฟลว์

สามขั้นตอนที่มีชื่อ ดำเนินการตามลำดับนี้ อย่าข้ามข้อใดในครั้งแรกที่คุณลองคู่นี้

1. บริบท Maguyva

จัดทำดัชนีรีโพซิทอรีหนึ่งที่คุณรู้จักอยู่แล้ว เชื่อมต่อไคลเอนต์ MCP ที่คุณเขียนโค้ดอยู่แล้ว — Claude Code, Cursor, Codex CLI, VS Code, Windsurf หรือไคลเอนต์ที่เข้ากันได้กับ MCP อื่น ๆ Maguyva มีคู่มือการตั้งค่าสำหรับไคลเอนต์ MCP ที่มีเอกสารประกอบ 24 ตัว และสามารถเชื่อมต่อกับไคลเอนต์อื่น ๆ ที่รองรับการตั้งค่า MCP มาตรฐานได้

ถามคำถามหนึ่งข้อที่คุณสามารถประเมินได้ก่อนที่ใครจะเขียนอะไรเลย ‘การหมดอายุของเซสชันถูกจัดการที่ไหน และใครเรียกใช้มัน?’ เป็นก้าวแรกที่ดีกว่า ‘แก้ไข auth’ เรียกร้องการอ้างอิง เปิดผลลัพธ์ file.ext:line ติดตามสัญลักษณ์ ยืนยันการพึ่งพาที่คุณกำลังจะแตะต้อง

Maguyva เปิดเผยเครื่องมือ MCP ที่เน้นลูกค้า 11 ตัวครอบคลุมการค้นหา สัญลักษณ์ การวิเคราะห์การพึ่งพา การดึงไฟล์ บริบทรีโพซิทอรีและเวิร์กโฟลว์เครื่องมืออรรถประโยชน์ที่กำหนดผลลัพธ์ได้แน่นอน โหมดการดึงข้อมูลสี่แบบรวมกันเป็นผลลัพธ์ที่มีการจัดอันดับ; find_symbol เป็นเครื่องมือแยกต่างหากเมื่อคุณรู้ชื่ออยู่แล้ว เอกสารประกอบ อธิบายเส้นทางที่สั้นที่สุด: เริ่มต้นฟรี จัดทำดัชนีรีโพที่คุณรู้จักอยู่แล้ว เชื่อมต่อไคลเอนต์ จากนั้นถามคำถามหนึ่งข้อที่คุณสามารถตรวจสอบได้

สแนปช็อตมีการประทับเวลา เพื่อให้เอเจนต์บอกได้ว่ากำลังอ่านต้นไม้เวอร์ชันใด ข้อจำกัดตามจริงคืองานในเครื่องที่ยังไม่ซิงค์ หากการเปลี่ยนแปลงมีอยู่เฉพาะในไดเรกทอรีทำงานและยังไม่ได้พุช แผนที่บนคลาวด์ยังไม่มีมัน ไฟล์คำสั่ง (CLAUDE.md, AGENTS.md) ยังคงมีที่ทางที่นี่ สำหรับข้อตกลงและสิ่งที่ไม่ควรแตะต้อง มันไม่ใช่แผนที่ที่มีชีวิต ใช้สำหรับพฤติกรรม ใช้ Maguyva สำหรับข้อเท็จจริง

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

2. PR ของเอเจนต์

เอเจนต์ตัวเดียวกันตอนนี้เขียนการเปลี่ยนแปลงในไคลเอนต์ที่คุณจ่ายเงินไปแล้ว Maguyva ไม่ใช่ตัวแก้ไขโค้ดหรือตัวตรวจสอบ เอเจนต์ยังคงสร้าง diff คุณยังคงเปิด pull request บน GitHub หรือ GitLab เหมือนที่คุณเคยทำ

สิ่งที่ควรแตกต่างคือไฟล์แรก PR ควรระบุชื่อตัวจัดการที่อิมพลีเมนต์พฤติกรรมนั้นจริง ผู้เรียกที่จะพัง และการทดสอบที่จะล้มเหลวหากการเปลี่ยนแปลงนั้นผิด หากข้ามขั้นตอนที่ 1 ไป ขั้นตอนที่ 3 จะเสียความคิดเห็นไปกับการเปลี่ยนแปลงที่ลงจอดในแพ็กเกจผิด Greptile ยังคงสามารถค้นหาปัญหาเชิงระบบได้ มันไม่ควรต้องกู้คืนจากเส้นทางที่หลอนด้วย

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

3. การตรวจสอบของ Greptile

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

อ่านความคิดเห็นเหมือนที่คุณจะอ่านเพื่อนร่วมทีมที่ใส่ใจ: เปิดตำแหน่งที่อ้างอิง ตัดสินใจว่าผลการค้นพบนั้นถูกต้องหรือไม่ จากนั้นดำเนินการ ที่ที่ Greptile เสนอ ‘Fix with your Agent’ มันส่งปัญหา — เส้นทางไฟล์ หมายเลขบรรทัด โค้ดที่แนะนำ — ไปยัง Claude Code, Codex, Conductor, Cursor หรือ Devin ‘Fix All’ ส่งปัญหาทั้งหมดในการตรวจสอบนั้นในครั้งเดียว พวกเขายังมี Greptile MCP และปลั๊กอิน Claude Code สำหรับการส่งต่อนั้นด้วย Maguyva ไม่อยู่ในรายการเป้าหมายที่มีชื่อนั้น การขาดหายไปนั้นไม่ใช่ปัญหา Maguyva ทำงานของมันเสร็จแล้วในขั้นตอนที่ 1 เอเจนต์เขียนโค้ดที่เขียน PR นั้นคือฝ่ายที่ควรได้รับ payload การแก้ไข

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

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

วิธีรักษาความซื่อสัตย์ของการเสริมกันนี้

Maguyva มาก่อนเสมอ การตรวจสอบ PR ที่มีไฟล์ผิดก็ยังคงเป็นการตรวจสอบไฟล์ผิดอยู่ดี
Greptile มาทีหลังเสมอ ร่างที่อ้างอิงได้ดียังคงต้องการการอ่าน diff ระดับทั้งระบบ
อย่าขอให้ Maguyva เผยแพร่ความคิดเห็น PR มันไม่ทำอย่างนั้น
อย่าขอให้ Greptile เป็นชั้นการดึงข้อมูลแรกของเอเจนต์ในขณะที่มันยังคงเลือกเส้นทางอยู่ นั่นไม่ใช่งานที่ออกแบบไว้สำหรับแอป GitHub หรือ GitLab ของพวกเขา
อย่าประดิษฐ์ไปป์ไลน์ bash ที่ ‘ซิงค์’ ทั้งสองอย่าง PR คืออินเทอร์เฟซนั้น
ตรวจสอบทั้งสองฝั่งแยกกัน จัดทำดัชนีรีโพที่คุณรู้จักอยู่แล้ว ถามคำถามหนึ่งข้อที่คุณสามารถตรวจสอบได้ จากนั้นเปิด PR เล็ก ๆ และอ่านสิ่งที่ Greptile แสดงความคิดเห็นจริง ๆ

วงจรนี้กลายเป็นเรื่องธรรมดาเมื่อได้รับการตั้งชื่อแล้ว แผนที่ก่อน PR ของเอเจนต์ ตรวจสอบทีหลัง แต่ละผลิตภัณฑ์ยังคงอยู่ในฝั่งของ pull request ที่ตนเชี่ยวชาญ

// map first. review second. in that order.

การให้บริบทรีโพขนาดใหญ่แก่เอเจนต์ AI โดยไม่ต้องใช้ตัวสร้างดัชนีในเครื่อง

Fri, 14 Aug 2026 00:00:00 GMT

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

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

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

เมื่อไหร่ที่ตัวสร้างดัชนีในเครื่องกลายเป็นเครื่องมือที่ผิด

ดัชนีในเครื่องสันนิษฐานว่าโค้ดอาศัยอยู่บนเครื่องที่สอบถามมัน และในขนาดโมโนรีโพจริง สมมติฐานนั้นตึงเครียดแม้กระทั่งภายในตัวแก้ไขโค้ดตัวเดียว รีโพแค่ใหญ่กว่าที่คุณต้องการให้ ‘ร้อน’ บนแล็ปท็อปเท่านั้นเอง: คุณทำงานในแพ็กเกจเดียวในขณะที่รัศมีผลกระทบอยู่ห่างออกไปสามไดเรกทอรี และการจัดทำดัชนีเย็นครั้งแรกของต้นไม้สองล้านบรรทัดนั้นไม่ใช่สิ่งที่คุณอยากผ่านมันสองครั้ง — ไม่ว่าจะบนเครื่องของคุณเอง หรือบนตัวรัน CI ที่ไม่เคยโคลนต้นไม้นั้นมาก่อน หรือเพื่อนร่วมทีมควรจะสามารถสอบถามแผนที่เดียวกับที่คุณสอบถามได้ โดยไม่ต้องรอเครื่องของตัวเองต่อสู้กับดัชนีเดียวกันนั้น

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

และปัญหาเรื่องขนาดนั้นลึกซึ้งกว่า ‘มีไฟล์มากเกินไปที่จะวาง’ บนต้นไม้ขนาดใหญ่ คำถามที่น่าสนใจแทบจะไม่เคยเป็น ‘แสดงไฟล์นี้ให้ฉันดู’ — มันคือไฟล์ไหน สัญลักษณ์ไหน ใครเรียกใช้ การทดสอบไหน เอเจนต์ที่เริ่มด้วยการแสดงรายการ src/ และอ่านสามผลลัพธ์แรกจะพลาดตัวจัดการใน apps/api และไคลเอนต์ที่สร้างขึ้นใน packages/sdk ได้อย่างง่ายดาย สิ่งที่คุณต้องการคือการดึงข้อมูลที่สร้างจากต้นไม้ทั้งหมด จากนั้นจัดอันดับ จากนั้นอ้างอิง

‘บริบทรีโพขนาดใหญ่’ หมายความว่าอย่างไรกันแน่

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

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

อีกสิ่งหนึ่งที่ไฟล์คำสั่งทำให้คุณไม่ได้: CLAUDE.md และ AGENTS.md เป็นที่ที่ถูกต้องสำหรับข้อตกลงและพฤติกรรม แต่มันไม่ใช่แผนที่ที่มีชีวิต จัดอันดับ และสอบถามได้ของต้นไม้สองล้านบรรทัด ใช้กฎสำหรับพฤติกรรม ใช้ความฉลาดของรีโพสำหรับข้อเท็จจริง

เราสร้างแผนที่บนคลาวด์ คุณสอบถามมันจากไคลเอนต์ใดก็ได้

Maguyva คือชั้นบริบทโค้ดเบส MCP ระยะไกล คุณเชื่อมต่อ GitHub เลือกรีโพซิทอรีของคุณ แล้วปล่อยให้ระบบทำงานไปได้เลยในขณะที่ไปป์ไลน์บนคลาวด์แยกวิเคราะห์ต้นไม้ สร้างสัญลักษณ์และขอบกราฟ และรักษาแผนที่ที่จัดอันดับไว้ — ไม่ต้องใช้ตัวสร้างดัชนีในเครื่องเลย

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

จากนั้นคุณเชื่อมต่อไคลเอนต์ใดก็ได้ที่คุณใช้อยู่แล้วโดยเพิ่มคีย์ API ในการตั้งค่า MCP ของมัน มีคู่มือการตั้งค่าสำหรับไคลเอนต์ MCP ที่มีเอกสารประกอบ 24 ตัว และไคลเอนต์ที่เข้ากันได้กับ MCP อื่น ๆ ที่รองรับการตั้งค่ามาตรฐานก็สามารถเชื่อมต่อได้เช่นกัน หาก Cursor คือที่ที่คุณอาศัยอยู่ หน้า Cursor อธิบายขั้นตอนสำหรับเส้นทางนั้น เซิร์ฟเวอร์เดียวกันตอบสนอง Claude Code, VS Code, Windsurf, Codex CLI และอื่น ๆ

คุณไม่ได้เปลี่ยนตัวแก้ไขโค้ด คุณกำลังมอบพื้นผิวเครื่องมือให้เอเจนต์ของคุณ — เครื่องมือ MCP 11 ตัวครอบคลุมการค้นหา สัญลักษณ์ การวิเคราะห์การพึ่งพา การดึงไฟล์ และบริบทรีโพซิทอรี — พร้อมความครอบคลุมมากกว่า 279 ภาษาและเทคโนโลยีที่อิงข้อความ ซึ่งหมายถึงมากกว่าที่คุณคิดสำหรับโมโนรีโพที่เลิกเป็นภาษาเดียวไปนานแล้ว

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

คำแนะนำที่เป็นรูปธรรม

อย่าเริ่มด้วยการจัดทำดัชนีทั้งบริษัท นี่คือเส้นทางที่ได้ผล:

เลือกรีโพซิทอรีหนึ่งที่คุณรู้จักดีอยู่แล้ว — แพ็กเกจที่คุณสามารถประเมินด้วยตนเองมีค่ามากกว่าต้นไม้ที่ใหญ่ที่สุดที่คุณมี
เริ่มต้นฟรี: 3 รีโพ, 50,000 บรรทัดที่จัดทำดัชนี เครื่องมือทั้ง 11 ตัว ไม่มีโควตาคิวรีรายเดือน หากรีโพตัวแทนของคุณใหญ่กว่านั้น หน้าราคา แสดงรายการระดับพื้นที่ทำงาน ($0, $19, $49, $149) ตามความครอบคลุมที่จัดทำดัชนี — ไม่ใช่ตามจำนวนที่นั่ง
เชื่อมต่อ GitHub และรอให้การจัดทำดัชนีครั้งแรกเสร็จสิ้น คุณไม่ได้คอมไพล์อะไรในเครื่องเลย
เชื่อมต่อไคลเอนต์ MCP ของคุณ — บรรทัดการตั้งค่าไม่กี่บรรทัด Maguyva คือเซิร์ฟเวอร์ MCP ระยะไกล ดังนั้นจึงไม่มีปลั๊กอิน ไม่มีส่วนขยาย และไม่มีตัวแก้ไขโค้ดตัวที่สองให้ต้องนำมาใช้
ถามคำถามหนึ่งข้อที่คุณสามารถตรวจสอบได้ ‘อะไรพึ่งพา parseConfig?’ หรือ ‘การหมดอายุของเซสชันล็อกอินถูกจัดการที่ไหน?’ จากนั้นเปิดผลลัพธ์ที่มีการอ้างอิง file.ext:line และตรวจสอบกับต้นไม้ที่อยู่ตรงหน้าคุณ
หลังจากที่การอ้างอิงพิสูจน์ตัวเองผ่านการสัมผัสกับต้นไม้นั้นเท่านั้น คุณจึงปล่อยให้เอเจนต์แก้ไข

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

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

สิ่งที่ควรจับตาดูหลังจากเชื่อมต่อ

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

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

// no laptop got hot building this map.

ทำไมเอเจนต์เขียนโค้ด AI ของคุณจึงหลอนเส้นทางไฟล์

Fri, 14 Aug 2026 00:00:00 GMT

สัญญาณไม่ใช่เนื้อหาฟังก์ชันที่ผิด มันคือการเปลี่ยนแปลงที่มั่นใจในไฟล์ที่ไม่มีอยู่จริง หรือในไฟล์ที่มีอยู่จริงแต่ไม่ใช่ไฟล์ที่อิมพลีเมนต์พฤติกรรมนั้น

คุณขอให้แก้ไขการหมดอายุของเซสชัน เอเจนต์เปิด src/auth/session.ts เส้นทางนั้นน่าเชื่อถือ มันก็ผิดด้วย ตัวจัดการจริงอาศัยอยู่ใน apps/api/src/middleware/expiry.ts ซึ่งถูกเปลี่ยนชื่อสองรอบการปรับโครงสร้างที่แล้ว เอเจนต์ไม่ได้โกหกคุณ มันกำลังเติมสตริงรูปร่างเหมือนเส้นทางให้สมบูรณ์ตามอคติจากการฝึกฝนบวกกับสิ่งใดก็ตามที่มีอยู่แล้วในหน้าต่างบริบท

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

ทำไมเอเจนต์จึงประดิษฐ์เส้นทาง

เอเจนต์เขียนโค้ดคือโมเดลทำนาย token ถัดไปที่มีเครื่องมือติดตั้งอยู่ เมื่อคุณพูดว่า ‘แก้ไขการหมดอายุของเซสชัน’ มันต้องระบุชื่อไฟล์ก่อนที่มันจะอ่านหรือแก้ไขอะไรได้ หากมันยังไม่มีแผนที่ที่มีหลักฐาน มันจะสร้างเส้นทางจาก:

ข้อตกลงการตั้งชื่อที่มันเคยเห็นในรีโพซิทอรีอื่น src/auth/session.ts เป็นรูปแบบที่พบบ่อย
ไฟล์ที่มีอยู่ในการสนทนาแล้ว ซึ่งอาจเป็นไฟล์ที่คุณวางไว้เมื่อสัปดาห์ที่แล้ว ไม่ใช่ไฟล์ที่สำคัญตอนนี้
รายการไดเรกทอรีที่มันรันโดยบังเอิญ ไม่สมบูรณ์บนต้นไม้ขนาดใหญ่
ไฟล์คำสั่ง CLAUDE.md และ AGENTS.md บอกเอเจนต์ว่าจะประพฤติตัวอย่างไร มันไม่ใช่ดัชนีที่มีชีวิตของสัญลักษณ์ ผู้เรียก หรือเส้นทางปัจจุบัน

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

Grep ไม่ช่วยคุณที่นี่หากเอเจนต์ไม่ได้ค้นหาสตริงที่ถูกต้องตั้งแต่แรก เอเจนต์เดาเส้นทาง จากนั้นอ่านสิ่งที่เส้นทางนั้นส่งคืน จากนั้นแก้ไขมัน ก้าวแรกที่ผิดคือเส้นทาง ไม่ใช่ patch

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

การแก้ไขไฟล์ผิดคือปัญหาการดึงข้อมูล

คิดว่าเส้นทางที่ประดิษฐ์ขึ้นเป็นข้อผิดพลาดในการดึงข้อมูล ไม่ใช่ข้อบกพร่องทางบุคลิกภาพ

หากเอเจนต์ต้องส่งคืน path/file.ext:line ก่อนที่จะได้รับอนุญาตให้แก้ไข สองสิ่งจะเกิดขึ้น อย่างแรก คุณสามารถเปิดการอ้างอิงและปฏิเสธงานได้ภายในสิบวินาที อย่างที่สอง เอเจนต์ต้องสอบถามบางสิ่งที่รู้จักต้นไม้นั้นจริง ๆ

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

Maguyva คือชั้นนั้นสำหรับเอเจนต์เขียนโค้ดที่เข้ากันได้กับ MCP มันไม่ใช่ตัวแก้ไขโค้ด Claude Code, Cursor, Codex CLI, VS Code, Windsurf และไคลเอนต์ MCP อื่น ๆ ยังคงอยู่ในตำแหน่งของมัน เอเจนต์สอบถามแผนที่ที่มีการจัดอันดับก่อนที่จะแตะบรรทัดใด ๆ

สิ่งที่อ้างนั้นเรียบง่ายโดยตั้งใจ: การเปลี่ยนแปลงที่หลอนน้อยลง Maguyva ไม่ได้เอาความสามารถในการเดาไปจากโมเดล มันเปลี่ยนก้าวแรกเริ่มต้นจาก ‘ประดิษฐ์เส้นทางที่น่าเชื่อถือ’ เป็น ‘ขอตำแหน่งที่จัดอันดับและอ้างอิงได้’

คำตอบที่มีหลักฐานมีลักษณะอย่างไร

คำตอบที่มีประโยชน์สำหรับ ‘การหมดอายุของเซสชันถูกจัดการที่ไหน’ ไม่ใช่ย่อหน้าเดียว มันคือรายการตำแหน่งสั้น ๆ:

apps/api/src/middleware/expiry.ts:48 - ตัวจัดการ
apps/web/src/lib/auth-client.ts:112 - ผู้เรียก
apps/api/tests/expiry.test.ts:20 - การทดสอบที่จะล้มเหลวหากการเปลี่ยนแปลงนั้นผิด

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

Maguyva เปิดเผยเครื่องมือ MCP ที่เน้นลูกค้า 11 ตัวครอบคลุมการค้นหา สัญลักษณ์ การวิเคราะห์การพึ่งพา การดึงไฟล์ บริบทรีโพซิทอรีและเวิร์กโฟลว์เครื่องมืออรรถประโยชน์ที่กำหนดผลลัพธ์ได้แน่นอน โหมดการดึงข้อมูลสี่แบบ (เชิงความหมาย เชิงโครงสร้าง เชิงกราฟ/การพึ่งพา และข้อความ) รวมกันเป็นผลลัพธ์ที่มีการจัดอันดับ; การค้นหาสัญลักษณ์เป็นเครื่องมือ MCP แยกต่างหาก (find_symbol) คำตอบที่มีหลักฐานกลับมาพร้อมเส้นทางไฟล์และหมายเลขบรรทัด เพื่อให้คุณประเมินมันเทียบกับต้นไม้ที่อยู่ตรงหน้าคุณ

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

วงจรที่เปลี่ยนการเปลี่ยนแปลงแรก

คุณไม่ต้องการศาสนาเวิร์กโฟลว์ใหม่ คุณต้องการก้าวเพิ่มเติมหนึ่งก้าวก่อนการเขียนครั้งแรก

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

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

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

ความล้มเหลวที่เกี่ยวข้องคือไฟล์เกือบถูกต้อง: เอเจนต์เปิด auth.ts ในขณะที่พฤติกรรมอาศัยอยู่ใน auth-client.ts หรือ patch ไฟล์ที่สร้างขึ้นแทนที่จะเป็นแหล่งที่มา หรือแก้ไขสำเนาใน packages/legacy เพราะชื่อตรงกัน การอ้างอิงไม่ได้ทำให้ข้อผิดพลาดเหล่านี้เป็นไปไม่ได้ มันทำให้มองเห็นได้ก่อนที่ diff จะลงจอด

สิ่งที่แผนที่จะไม่แก้ไขให้คุณ

จงซื่อสัตย์เกี่ยวกับสิ่งที่คุณได้รับ แผนที่ที่มีหลักฐานจะไม่ทำให้ทุกการเปลี่ยนแปลงถูกต้อง — เอเจนต์ของคุณยังคงสามารถเขียน patch ที่แย่บนไฟล์ที่ถูกต้องเป๊ะได้ หากโค้ดเบสของคุณพึ่งพาการเรียกเมธอดแบบไดนามิก รีเฟลกชัน หรือการแพตช์โค้ดขณะรันไทม์ การค้นหาสัญลักษณ์บางอย่างจะให้ผลลัพธ์ที่บางกว่าที่คุณต้องการ เพราะนั่นคือสิ่งที่ความไม่ชัดเจนของรันไทม์ทำกับดัชนีแบบสแตติกใด ๆ และหากคุณคาดหวังเปอร์เซ็นต์ — ‘เส้นทางที่หลอนลดลง X%’ — คุณจะไม่พบมันที่นี่ เพราะไม่มีใครสามารถวัดตัวเลขนั้นได้อย่างซื่อสัตย์สำหรับรีโพของคุณนอกจากคุณเอง

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

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

// it doesn't know the file. it knows how to find it.

เหตุใดเราจึงอัปเกรดการค้นหาโค้ดเป็น voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

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

Semantic search จะดีได้เพียงใด ขึ้นอยู่กับคุณภาพของเอ็มเบดดิ้งที่รองรับมัน

เมื่อ agent ถาม Maguyva ว่า “เราจัดการ retry ตรงไหน” มันไม่ได้ grep หาคำว่า “retry” มันกำลังถามหา ความหมาย — ลูป backoff, circuit breaker, สิ่งที่ห่อการเรียกที่ไม่เสถียร คำถามนั้นถูกตอบโดยโมเดลเวกเตอร์ที่แปลงโค้ดให้เป็นจุดในพื้นที่แล้วหาเพื่อนบ้าน เลือกโมเดลที่ดีกว่า แล้วทุกคิวรี semanticในผลิตภัณฑ์จะคมชัดขึ้นอย่างเงียบๆ

เราจึงเปลี่ยนของเรา ณ เดือนมิถุนายน 2026 เอ็มเบดดิ้งโค้ดของ Maguyva รันบน voyage-4-large แทนที่ voyage-code-3

เบนช์มาร์ก

เราไม่ได้ตัดสินใจนี้ด้วยความรู้สึก Retrieval Embedding Benchmark (RTEB) สาธารณะจัดอันดับโมเดลเอ็มเบดดิ้งบนงาน retrieval จริง และบนตารางอันดับ Code ของมัน voyage-4-large อยู่ที่ อันดับหนึ่งโดยรวม (90.86) — นำหน้า gemini-embedding-2-preview (90.26) และที่น่าสังเกตคือ นำหน้าโมเดลที่เราใช้อยู่แล้ว voyage-code-3 (89.73, อันดับ 3)

นั่นคือความต่างของคะแนนจริงที่ไม่มาก แต่มันคือช่องว่างในทิศทางที่ถูกต้อง บนเบนช์มาร์กสาธารณะ ในงานที่เราสนใจอย่างแท้จริง: การค้นคืนโค้ดตามความหมาย

การแลกเปลี่ยนที่เรายอมรับ: Binary Quantization

นี่คือส่วนที่บทความ “เราอัปเกรดโมเดลของเรา” ส่วนใหญ่มักละไว้

Maguyva ไม่เก็บเวกเตอร์แบบ full-precision เราเก็บเอ็มเบดดิ้งแบบ ไบนารีควอนไทซ์: เวกเตอร์ 2048 มิติแต่ละตัวยุบเหลือซิกเนเจอร์ 2048 บิต — 256 ไบต์ต่อเวกเตอร์ ซิกเนเจอร์เหล่านั้นถูกค้นด้วย Hamming distance มีดัชนีและแบ่งพาร์ติชันแยกตามเทแนนต์

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

voyage-4-large เข้ากับดีไซน์นี้โดยไม่ต้องบังคับให้ย้ายชั้นพื้นที่จัดเก็บ: มันสร้างผลลัพธ์ 2048 มิติ เหมือนกับ voyage-code-3 ดังนั้นคอลัมน์ bit(2048) และเส้นทาง Hamming search ของเราจึงไม่เปลี่ยนแปลง โมเดลดีขึ้น schema ยังคงเดิม

โค้ดเป็นแค่จุดเริ่มต้น

Maguyva คือเครื่องมือโค้ดอินเทลลิเจนซ์ แต่เรายังเป็นลูกค้ารายแรกของตัวเองด้วย และเราชี้มันไปยังอีกสิ่งหนึ่ง: markdown ที่อยู่ในรีโพของเราข้างๆ โค้ด บันทึกการตัดสินใจเชิงสถาปัตยกรรม, runbook, สัญญา, เอกสารการเงินและนโยบาย — ทั้งหมดถูกควบคุมเวอร์ชันใน Git ทั้งหมดอยู่หลัง MCP เซิร์ฟเวอร์เดียวกัน ดัชนีเชิงความหมายเหนือ เอกสาร ไม่ใช่แค่ซอร์สโค้ด

นั่นคือเหตุผลที่ความกว้างของ voyage-4-large สำคัญพอดี ใน RTEB ตารางอันดับตระกูลเดียวกันนี้ มันคือ อันดับหนึ่งด้านการเงิน อันดับหนึ่งด้าน healthcare และอันดับหนึ่งด้านการค้นคืนข้อความโดยรวม — นำหน้า Gemini Embedding ของ Google, Embed v4 ของ Cohere และ text-embedding-3-large ของ OpenAI (Voyage เป็นผู้ร่วมสร้าง RTEB ดังนั้นเราจึงอ่านมันเป็นสัญญาณสาธารณะที่แข็งแกร่ง มากกว่าจะเป็นกรรมการที่เป็นกลางอย่างสมบูรณ์แบบ — แต่มันถูกเบนช์มาร์กแบบตัวต่อตัวกับโมเดลเชิงพาณิชย์หลักทุกตัว บนชุดข้อมูลที่กันไว้ทดสอบและไม่ได้เปิดเผยต่อสาธารณะ) ดัชนีเดียวกันที่หาฟังก์ชันที่ถูกต้องให้ agent ก็หาข้อสัญญาที่ถูกต้องในสัญญาหรือบรรทัดที่ถูกต้องในนโยบาย — และในโดเมนเหล่านั้น voyage-4-large ไม่ใช่การประนีประนอม มันคือผู้นำ

เหตุใดเราจึงจ่ายเงินเพื่อ Embedding ระดับพรีเมียม

มีวิธีค้นหาที่ถูกกว่า และหลายวิธีก็ฟรี การค้นหาเชิงคำศัพท์ — BM25 และญาติของมัน — จับคู่คำสำคัญ รันในเครื่อง และไม่มีค่าใช้จ่าย โมเดลเอ็มเบดดิ้งแบบโอเพนซอร์สอย่าง BGE, Nomic และ embeddinggemma ให้การค้นคืนเชิงความหมายที่ พอใช้ได้ จริง และคุณสามารถโฮสต์เองได้ในราคาของ GPU หนึ่งตัว Maguyva ใช้ฝั่งฟรีด้วยเหมือนกัน: ทุกคำค้นผสาน text, AST, graph และ semantic search เข้าด้วยกัน สิ่งที่เราไม่ลดต้นทุนจนเสียคุณภาพคือชั้น semantic

เราจ่ายเงินต่อ token สำหรับเอ็มเบดดิ้งระดับพรีเมียม — voyage-4-large — แทนที่จะโฮสต์โมเดลฟรีเอง ด้วยเหตุผลสองข้อ ข้อแรก การค้นหาด้วยคำสำคัญ อย่างเดียวตอบ “เราจัดการ retry ตรงไหน” ไม่ได้ เมื่อโค้ดเขียนว่า backoff และ circuit breaker และไม่เคยพูดคำว่า “retry” เลย — ความหมายคือประเด็นทั้งหมดของเอ็มเบดดิ้ง และในโดเมนที่เราให้บริการ โมเดลแบบเปิดยังตามหลังโมเดลพรีเมียมอยู่: ตามหลังไม่กี่คะแนนในข้อความทั่วไป และตามหลังมากกว่านั้น ในกลุ่มเฉพาะอย่างโค้ด สัญญา และการเงิน ข้อสอง จากประสบการณ์ของเรา คุณภาพการค้นคืนหล่อหลอมคำตอบสุดท้ายมากกว่าโมเดลที่อยู่อีกฝั่งหนึ่ง — agent ที่แข็งแกร่งแต่ได้รับบริบทผิดก็ยังตอบผิดอยู่ดี และมันไม่มีวันเห็นเอกสารที่มันไม่เคยได้รับ

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

ส่วนที่ตรงไปตรงมา

เอกสารของ Voyage เองยังคงระบุว่า voyage-code-3 เป็นโมเดลที่ปรับให้เหมาะกับโค้ด แล้วทำไมถึงย้าย?

เพราะเราอ่านเบนช์มาร์กสาธารณะ ไม่ใช่แค่ตารางโมเดลของ vendor และเบนช์มาร์กจัดให้ voyage-4-large อยู่อันดับหนึ่งสำหรับการค้นคืนโค้ด นี่คือการตัดสินใจแบบมองไปข้างหน้า: เลือกโมเดลที่ใหม่กว่าและแข็งแกร่งกว่าโดยทั่วไป แล้วยืนยันมันกับตารางอันดับสาธารณะบนงานที่สำคัญ เราสบายใจที่จะเดิมพันแบบนี้เพราะหลักฐานนั้นกว้าง — voyage-4-large ไม่ได้แค่ชนะบนโค้ด มันยังนำในการเงิน healthcare และการค้นคืนโดยรวมด้วย

รากฐานที่ไม่เด่นสะดุดตา

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

การพัฒนาตนเองเชิงเวียนซ้ำของภาษา: ขัดเกลาโค้ดอินเทลลิเจนซ์ ครอบคลุมราว 280 ภาษา

Tue, 26 May 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (พฤษภาคม 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

Maguyva ดึงสัญลักษณ์ การอ้างอิง และ dependency กราฟ จากซอร์สโค้ดในราว 280 ภาษา แต่ละภาษาคือตัวจัดการ tree-sitter ที่พัฒนาขึ้นเฉพาะ — คิวรี ฮิวริสติก กรณีขอบ — และแต่ละตัวจัดการสามารถผิดพลาดในแบบที่ละเอียดอ่อนของตัวเองได้ การเรียกเมธอดที่ถูกปล่อยออกมาเป็นการอ่าน ฟังก์ชันที่ถูกระบุว่าเป็นของขอบเขตที่ห่อหุ้มผิด ความสัมพันธ์ที่ไม่มีอยู่จริงเลย

คุณตรวจสอบด้วยมือไม่ได้ ไม่มีทีมไหนอ่านผลการแตกโครงสร้างข้าม 280 ไวยากรณ์แล้วจับ edge ที่ไม่ดีได้ ดังนั้นคำถามที่น่าสนใจไม่ใช่ “การแตกโครงสร้างของเราถูกต้องหรือไม่” — แต่เป็น “คุณจะ ค้นพบ ว่ามันผิดได้อย่างไร ในระดับความกว้างนี้ โดยไม่มีมนุษย์อยู่ในทุกลูป” คำตอบของเราคือการพัฒนาตนเองเชิงเวียนซ้ำของภาษา: ลูปคุณภาพที่ขับเคลื่อนโดย agent ประจำภาษา, LLM ที่ทำหน้าที่เป็นผู้ตัดสิน และกฎหนึ่งข้อที่เรายังคงเรียนรู้ซ้ำแล้วซ้ำเล่า: เขียวไม่เท่ากับถูกต้อง

เขียวไม่ใช่ถูกต้อง

ทุกภาษามีชุด fixture และเกณฑ์การปล่อยใช้งานให้คะแนนมันครอบคลุมห้ามิติ — ความแม่นยำ, ความสมบูรณ์เชิงโครงสร้าง, ความครบถ้วน, คุณภาพ และประสิทธิภาพ ภาษาหนึ่งจะเป็น สีเขียว (GREEN) ก็ต่อเมื่อ บน fixture ของมัน precision ≥ 0.95, recall ≥ 0.99 และ F1 ≥ 0.97 พร้อม edge ที่คาดหวังอย่างน้อย 20 edge เพื่อความเชื่อมั่นทางสถิติ ต่ำกว่านั้นคือ YELLOW หรือ RED และมันจะไม่ถูกปล่อยออกมา

เกณฑ์นั้นจำเป็นแต่ไม่เพียงพอ fixture ตรวจสอบกับ fixture ที่เราเขียนเอง มันเข้ารหัสกรณีที่เราคิดไว้แล้ว ตัวจัดการหนึ่งอาจไร้ที่ติบน fixture ของมัน แต่ยังคงบิดเบือนรูปแบบที่ปรากฏเฉพาะในโค้ดจริง — สำนวนแมโคร เมธอดที่ผูกกับเจเนอริก ฟีเจอร์ภาษาที่ไม่มีใครเขียน fixture ให้ GREEN หมายความว่า fixture ผ่าน มันไม่ได้หมายความว่ารีโพซิทอรีจริงจะแตกโครงสร้างได้สะอาด ดังนั้นลูปนี้ต้องละทิ้ง fixture แล้วมองไปที่โลกจริง

ลูปด้านใน: สุ่มตรวจ ตัดสิน แก้ไข พิสูจน์

ลูปหลักรันทีละภาษา:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

มีไม่กี่อย่างที่ทำให้สิ่งนี้ทำงานได้จริง แทนที่จะดิ้นอยู่กับที่

ผู้ตัดสินคือ agent เอง ไม่ใช่การเรียก API เมื่อเราพูดว่า “LLM เป็นผู้ตัดสิน” เราหมายถึง agent ประจำภาษาเองอ่าน edge ที่สุ่มมาแต่ละตัวเทียบกับซอร์สจริง แล้วจำแนกมันด้วยหลักเกณฑ์การตัดสินห้าประเภทที่ตายตัว: edge นี้ถูกต้องหรือไม่ เป็นผลบวกลวง เป็นความสัมพันธ์ที่ถูกต้องแต่ประเภทผิด ผูกกับขอบเขตผิด หรือพก metadata ผิด หลักเกณฑ์การตัดสินนั้นคือทั้งหมดของเกม — “อัตราความผิดพลาด 23%” ไม่มีความหมายจนกว่าคุณจะรู้ว่านั่นคือข้อบกพร่องจริงหรือผู้ตัดสินนับผิด

แก้ไขทีละอย่าง แล้วพิสูจน์มัน แต่ละรอบเปลี่ยนแปลงส่วนที่แก้ไขได้เพียงหนึ่งส่วนเท่านั้น แล้วรันซ้ำกับชุดทดสอบที่ตายตัว และเก็บการเปลี่ยนแปลงไว้ก็ต่อเมื่อ F1 ดีขึ้นและการจำแนกซ้ำดูดีขึ้น ถ้าไม่ มันจะถูกย้อนกลับ ไม่มีชุดการแก้ไขแบบเดาสุ่ม ไม่มี “น่าจะดีขึ้น” การเปลี่ยนแปลงต้องพิสูจน์คุณค่าของมันเอง ไม่เช่นนั้นก็หายไป และเมื่อการแก้ไขผ่านเกณฑ์และถูกเก็บไว้ มันจะถูกเลื่อนขึ้นเข้าสู่ชุด fixture — เพื่อให้ bug ที่มันแก้ไม่สามารถกลับมาเงียบๆ ได้อีก ขั้นตอนการเลื่อนขึ้นนั้นคือสิ่งที่ทำให้ลูปนี้ เวียนซ้ำ แทนที่จะเป็นแค่การทำซ้ำ: ทุกรอบจะทำให้มาตรฐานอ้างอิงที่รอบถัดไปใช้ตรวจสอบแข็งแกร่งขึ้น

บทเรียนที่เรายังคงเรียนรู้ซ้ำ: เมตริกรายงานเกินจริง

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

ตัวอย่างที่ชัดที่สุด: llvm เคยแสดงอัตรา “ซอร์สที่ไม่มี symbol” ที่ 73% และถูกตราหน้าว่าเลวร้าย เราเจาะลึกเข้าไป ความแม่นยำจริง คือ 98.5% “symbol ที่หายไป” เกือบทั้งหมดเป็นการอ้างอิงภายนอกที่ถูกต้อง — การเรียกเข้าไลบรารีมาตรฐาน เข้าเฟรมเวิร์ก เข้าโค้ดที่อยู่นอกรีโพ เมตริกนั้นกำลังวัดคุณสมบัติของภาษา ไม่ใช่ข้อบกพร่องในตัวจัดการ ภาษาอย่าง Zig, COBOL และ Odin แสดงอัตรา “กำพร้า” 65–70% และถูกต้องทั้งหมด COBOL มีความผิดพลาดจริงเป็นศูนย์

หากเราปล่อยให้ตัวเลขเหล่านั้นขับเคลื่อนงาน เราคงใช้เวลาหลายสัปดาห์ “แก้ไข” ตัวจัดการที่ถูกต้องอยู่แล้ว และมองข้ามภาษาที่มี bug จริงแบบเงียบๆ บทสรุปนั้นตรงไปตรงมา: เมตริกรวมเป็นสัญญาณคัดกรองคร่าวๆ อย่างดีที่สุด สัญญาณคุณภาพจริงคือการสุ่มตรวจพร้อมการจำแนก edge — การมอง edge จริงในรีโพซิทอรีจริง และตัดสินทีละตัว ข้อมูลเหนือสัญชาตญาณ แต่ก็ต่อเมื่อคุณรู้แล้วว่าข้อมูลไหนบอกความจริง

ลูปด้านนอก: ทีมงาน ไม่ใช่มาราธอน

ทีละภาษาจะใช้เวลานานมากข้าม 280 ภาษา ดังนั้นลูปด้านในจึงถูกห่อด้วยลูปด้านนอกที่รันหลายภาษาพร้อมกัน

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

แต่ละ agent ทำงานใน worktree แบบใช้แล้วทิ้งเพื่อไม่ให้เหยียบกันเอง ออร์เคสเตรเตอร์รวมการแก้ไขของพวกมันทีละอย่าง แต่ละครั้งอยู่หลังการตรวจสอบการถดถอยแบบ full-manifest: การเปลี่ยนแปลงที่ช่วยภาษาของตัวเองแต่แอบทำลายอีกสามภาษาจะไม่ถูกรวมเข้ามา การรวมเข้ามาถูกควบคุม และยืนยันก่อนที่อะไรจะถูก push — เกณฑ์การถดถอยตัดสินว่าอะไร ปลอดภัย มนุษย์ยังคงตัดสินว่าอะไร ถูกปล่อยออกมา จากนั้น pool จะหมุนไปยังชุดภาษาถัดไป และทั้งหมดก็รันอีกครั้ง

สิ่งที่ยังไม่สมบูรณ์แบบ

ผู้ตัดสินสามารถผิดพลาดได้ และความผิดพลาดนั้นมีทิศทาง: agent ที่รันด้วยบริบทน้อยเกินไป รายงานเกินจริง ในชุดหนึ่ง ภาษาแปดภาษาถูกตั้งค่าสถานะที่ความผิดพลาด 5–20% เมื่อตรวจสอบ มีเพียงหนึ่งภาษาที่เป็น bug จริงเฉพาะภาษา — ที่เหลือเป็นความผิดพลาดของผู้ตัดสินจากการพลาด semantic เฉพาะของภาษานั้น (บรรทัดซอร์สหนึ่งบรรทัดปล่อย edge หลายตัวอย่างถูกต้อง, การผูกพารามิเตอร์ถูกจำลองเป็นการกำหนดค่า, ภาษาที่มีการอ้างอิงต่อหนึ่งตัวระบุ) นั่นคือเหตุผลที่เราสุ่มด้วยสองซีดแล้วตรวจไขว้ และเหตุผลที่ความไม่ลงรอยกันระหว่างผู้ตัดสินกับ fixture ถูกมองว่าเป็นสัญญาณที่ น่าสนใจที่สุด ไม่ใช่คำตัดสินที่ยุติแล้ว — บางครั้ง fixture ต่างหากที่เป็นสิ่งที่ผิด

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

ได้มา ไม่ใช่แค่กล่าวอ้าง

ทุกสิ่งที่ Maguyva ทำให้ agent — การหาสัญลักษณ์, การตามรอย dependency, การตอบคำถามพร้อมโค้ดที่อ้างอิงได้ — ล้วนพึ่งพาการแตกโครงสร้างที่อยู่ข้างล่างว่าถูกต้อง ข้าม 280 ภาษา คำว่า “ถูกต้อง” ไม่สามารถกล่าวอ้างได้ มันต้อง ได้มา อย่างต่อเนื่องจากโค้ดจริง ลูปนี้คือวิธีที่เราได้มันมา: วงจรสุ่มตรวจและแก้ไขแบบอัตโนมัติที่ปฏิบัติต่อเมตริกของตัวเองด้วยความสงสัย พิสูจน์ทุกการเปลี่ยนแปลง และเปลี่ยนทุกการแก้ไขให้เป็นเครื่องป้องกันการถดถอยครั้งถัดไป มันไม่ใช่เรื่องหรูหรา มันคืองานที่ทำให้เราพูดได้ว่า “เรารองรับภาษาของคุณ” และหมายความอย่างนั้นจริงๆ เขียวนั้นง่าย ถูกต้องนั้นต้องได้มา

ค้นหาแบบผสานหลายโหมด: เลือกตัวค้นคืนที่ใช่สำหรับทุกคำค้น

Wed, 15 Apr 2026 00:00:00 GMT

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

คำค้นหาแต่ละแบบต้องการสิ่งที่ต่างกัน

“parseConfig ถูกนิยามที่ไหน” ต้องการสัญลักษณ์ที่แน่นอน — ตำแหน่งเดียวที่แม่นยำ เร็ว “authentication ทำงานอย่างไร” ต้องการความหมาย — การกระจายของโค้ดที่เกี่ยวข้องซึ่งอธิบายแนวคิด “อะไรจะพังถ้าฉันเปลี่ยนฟังก์ชันนี้” ต้องการ dependency graph “หาสตริง ECONNREFUSED” ต้องการการจับคู่แบบตรงตัว ไม่ต้องมีอะไรฉลาด

Grep ยอดเยี่ยมสำหรับการจับคู่แบบตรงตัวและมีประโยชน์สำหรับการตามหาการอ้างอิงบางอย่าง แต่มันไม่ใช่ dependency graph และมันไม่เข้าใจความหมาย Embedding ครอบคลุมด้าน semantic แต่มันเป็นเครื่องมือที่ผิดสำหรับสตริงตรงตัวและการวิเคราะห์ผลกระทบ เครื่องมือค้นหาโค้ดส่วนใหญ่เลือกเอนจินเดียวและให้ทุกคำค้นอยู่กับตัวเลือกนั้น Maguyva ไม่ยึดติดกับเอนจินเดียว มันหาให้ได้ว่าคุณถามคำถามประเภทไหน แล้วผสมตัวค้นคืนสี่ตัวในสัดส่วนที่คำถามนั้นสมควรได้รับ

สี่รูปแบบ

ภายใต้ระบบมีสี่วิธีอิสระในการหาโค้ด:

semantic — การค้นหาเวกเตอร์บน Voyage binary embedding หาโค้ดตามความหมาย
text — การจับคู่ trigram หาข้อความตรงตัว, สตริงข้อผิดพลาด, ตัวระบุที่แน่นอน
structural — AST คิวรี หาคำนิยาม, ซิกเนเจอร์ และโครงสร้างภาษา
graph — dependency graph หาผู้เรียก, สิ่งที่ถูกเรียก และรัศมีผลกระทบ

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

การจำแนกเจตนา

ก่อนที่การค้นคืนใดจะรัน ตัวจำแนกที่ใช้ทรัพยากรน้อยจะจัดคำค้นให้อยู่ในหนึ่งในหกเจตนา พร้อมคะแนนความมั่นใจ มันตั้งใจให้ราคาถูก — ฮิวริสติกที่เรียงลำดับ การจับคู่แรกชนะ — เพราะมันรันบนเส้นทางที่ใช้งานบ่อย และเพิ่มเวลาแค่หนึ่งหรือสองมิลลิวินาที:

เริ่มด้วย def , class , func , import … → find_definition (ความมั่นใจ 0.95)
“who calls”, “usages of”, “references to” (ใครเรียก การใช้งานของ การอ้างอิงถึง) → find_references (0.90)
“impact”, “blast radius”, “what depends on” (ผลกระทบ รัศมีผลกระทบ สิ่งที่พึ่งพา) → impact_analysis (0.90)
"string" ที่ใส่เครื่องหมายคำพูด หรือโทเคนข้อผิดพลาดอย่าง traceback → exact_match (0.85–0.90)
ตัวระบุแบบ CamelCase หรือ snake_case → find_definition (0.60–0.80)
“how”, “why”, “explain”, “architecture” (อย่างไร ทำไม อธิบาย สถาปัตยกรรม) → understand_code (0.75)
ไม่มีอะไรตรง → understand_code ความมั่นใจต่ำ (0.40)

แต่ละเจตนามีโปรไฟล์น้ำหนักข้ามสี่รูปแบบ นี่คือตัวเลขจริง:

เจตนา	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

ดังนั้น “parseConfig ถูกนิยามที่ไหน” จะเอนหนักไปทาง AST (0.6) “auth ทำงานอย่างไร” เอนไปทาง semantic เวกเตอร์ (0.5) “อะไรพึ่งพาสิ่งนี้” แทบทั้งหมดเป็น graph (0.7) “หา ECONNREFUSED” แทบทั้งหมดเป็น trigram (0.9) โดยปิดโมเดล embedding ไปเลย — เพราะความคล้ายคลึงเชิงความหมายเป็นเครื่องมือที่ผิดโดยสิ้นเชิงสำหรับสตริงที่แน่นอน

เส้นทางด่วน และเส้นทางที่ผสมแล้ว

เมื่อตัวจำแนกมั่นใจ — คะแนน ≥ 0.85 — และคำค้นเป็นแบบปกติ Maguyva ข้ามการผสมทั้งหมด แล้วส่งตรงไปยังรูปแบบหลักที่ครองอยู่ “X ถูกนิยามที่ไหน” ไม่ต้องการตัวค้นคืนสี่ตัว มันต้องการดัชนี AST ทันที เส้นทางตรงนั้นถูกรายงานกลับมาเป็น fusion_strategy: "direct"

ทุกอย่างที่คลุมเครือจะผ่านการผสม สี่รูปแบบ (หรือสามบนพรีเซ็ตเริ่มต้น) รันคู่ขนานกัน แต่ละอย่างคืนรายการจัดอันดับของตัวเอง แล้วเรารวมพวกมัน

Weighted Reciprocal Rank Fusion

การผสมตัวค้นคืนที่แตกต่างกันนั้นยากกว่าที่ฟังดู: ความคล้ายคลึงแบบโคไซน์ 0.82, คะแนน trigram 137 และความเป็นศูนย์กลางของกราฟ 0.004 ไม่ได้อยู่บนมาตราส่วนเดียวกัน ดังนั้นคุณบวกมันตรงๆ ไม่ได้ Reciprocal Rank Fusion หลบเลี่ยงปัญหาด้วยการทิ้งคะแนนดิบไป แล้วเก็บไว้แค่ อันดับ ที่แต่ละเอนจินกำหนดให้ การมีส่วนร่วมของผลลัพธ์หนึ่งจากรูปแบบหนึ่งคือ:

contribution = weight × 1 / (k + rank + 1)

โดยที่ rank คือตำแหน่งของมันในรายการของรูปแบบนั้น และ k คือค่าคงที่ทำให้เรียบ การมีส่วนร่วมจะถูกรวมข้ามรูปแบบสำหรับผลลัพธ์ใดๆ ที่มากกว่าหนึ่งเอนจินพบ — ความสอดคล้องระหว่างตัวค้นคืนลอยขึ้นไปด้านบนตามธรรมชาติ เราใช้ k = 40 บนพรีเซ็ตเริ่มต้น และ 60 บน thorough (quick รันแบบ semantic-only เท่านั้น ดังนั้นการผสมจึงไม่เคยเข้ามาเกี่ยวข้องที่นั่น) งาน RRF ดั้งเดิมลงเอยที่ k = 60 สำหรับการค้นคืนเอนกประสงค์ ค่าเริ่มต้นของเราให้น้ำหนักเพิ่มขึ้นเล็กน้อยกับผลลัพธ์ที่หลายรูปแบบจัดไว้ในอันดับต้นๆ — และเราไม่แนะนำให้ปรับแต่งด้วยมือ

นอกจากนั้น ผลลัพธ์ยังพก การเพิ่มค่าตามความสำคัญของ graph ฮับ — ฟังก์ชันที่ทั้งโค้ดเบสพึ่งพา — ควรอยู่เหนือโหนดใบที่ไม่ค่อยมีใครรู้จักแม้ที่ความเกี่ยวข้องเชิงข้อความเท่ากัน ดังนั้นเราคูณการมีส่วนร่วมแต่ละอย่างด้วย:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

ความเป็นศูนย์กลางมาจากเมตริก PageRank/ดีกรีที่คำนวณล่วงหน้าของ pipeline และการเพิ่มค่าถูกจำกัดที่ 1.5 เท่า เพื่อไม่ให้ฟังก์ชันยอดนิยมกลบฟังก์ชันที่ไม่ค่อยมีใครรู้จักแต่เกี่ยวข้องมากกว่าไปเสียหมด สุดท้ายเราลดอันดับผลลัพธ์จาก path ของ vendor, build และ archive และตัดซ้ำเหลือส่วนที่ดีที่สุดต่อไฟล์

สิ่งที่ยังไม่สมบูรณ์แบบ

ตัวจำแนกเจตนาเป็นชุดของนิพจน์ปรกติ ไม่ใช่โมเดลที่ฝึกมา มันจัดการรูปแบบคำค้นทั่วไปด้วยฮิวริสติก และคำค้นที่กำกวมจะใช้ understand_code กับการผสมผลที่ให้น้ำหนักด้านความหมายมากกว่า บทความฉบับก่อนระบุว่าได้ลดอัตราคำค้นที่ไม่มีผลลัพธ์จากประมาณ 15% เหลือต่ำกว่า 5% สำเร็จแล้ว แต่ข้อเสนอในเดือนธันวาคม 2025 ระบุเพียงค่าประมาณเริ่มต้นและเป้าหมาย โดยไม่ได้ให้ชุดคำค้นหรือบันทึกการวัดที่สนับสนุนผลดังกล่าว เราขอถอนข้อกล่าวอ้างว่าได้ปรับปรุงสำเร็จแล้วนี้ ดูหลักฐานต้นทางและข้อแก้ไข (ภาษาอังกฤษ) เรายังไม่ได้แทนที่ตัวจำแนกด้วยโมเดลที่ฝึกมา เพราะรุ่นต้นทุนต่ำนี้เร็วและดีพอสำหรับหน้าที่กำหนดเส้นทางที่ตั้งใจไว้ และตัวจำแนกที่ผิดแต่มั่นใจนั้นแย่กว่าทางเลือกสำรองที่ซื่อตรง น้ำหนักต่าง ๆ เป็นค่าตั้งต้นที่เลือกด้วยมือ ไม่ได้เรียนรู้จากข้อมูลการคลิกที่เราไม่ได้เก็บรวบรวม

ถามสิ่งที่ต้องการรู้ โดยไม่ต้องเลือกเครื่องมือเอง

agent ไม่ควรต้องรู้ว่าจะหยิบ grep หรือ embedding หรือ call graph ขึ้นมา — มันควรถามคำถามด้วยคำพูดธรรมดาแล้วได้คำตอบที่ถูกต้อง การผสานหลายโหมดคือสิ่งที่ทำให้ find_symbol, semantic search และการวิเคราะห์ dependency อยู่ภายใต้อินเทอร์เฟซคำค้นเดียว: ระบบอ่านรูปแบบของคำถามแล้วประกอบตัวค้นคืนที่ถูกต้องให้อย่างเงียบๆ โมเดลที่ให้คะแนน embedding สำคัญ แต่การรู้ว่าเมื่อไหร่ ไม่ควร ใช้มันก็สำคัญเช่นกัน การเลือกเครื่องมือที่ถูกต้องสำหรับแต่ละคำค้นเป็นคุณภาพชนิดหนึ่งในตัวมันเอง และเป็นชนิดที่เราอยากรับผิดชอบเองมากกว่าผลักให้ผู้เรียก

// you bring the question. it brings the tools.

การสังเกตการณ์เอเจนต์: Hooks, Alloy และ Grafana

Tue, 24 Mar 2026 00:00:00 GMT

ระบบ agent พังในรูปแบบที่แปลกๆ

บางครั้งโมเดลคือปัญหา บางครั้งเครื่องมือคือปัญหา บางครั้ง MCP เซิร์ฟเวอร์ของคุณก็ไม่มีอะไรผิด แต่ agent เลือกผู้เชี่ยวชาญผิดคน หรือใช้เวลาครึ่งเซสชันทำงาน shell ที่คุณไม่ได้คาดคิด หรือเผาผลาญต้นทุนอย่างเงียบๆ ในลูปที่ดูมีประสิทธิผลจากภายนอก

ถ้าคุณมองไม่เห็นความแตกต่าง แสดงว่าคุณไม่ได้กำลังควบคุมระบบ agent จริงๆ คุณกำลังเดา

เราจึงสร้าง observability สแตกสำหรับเวิร์กโฟลว์ของเราเอง: Claude Code, Codex, Claude hook อีเวนต์, Codex notify อีเวนต์, OpenTelemetry แบบเนทีฟ, Grafana Alloy และ Grafana Cloud อยู่อีกฝั่งหนึ่ง

ส่วนที่น่าสนใจไม่ใช่ “เราสร้างแดชบอร์ด” ส่วนที่น่าสนใจคือเราต้องแยกเทเลเมทรีออกเป็นสองสตรีมที่ต่างกัน เพราะไม่มีฟีดเดียวที่ให้ภาพรวมทั้งหมด

ปัญหา: เทเลเมทรีของ Agent กระจัดกระจาย

agent เขียนโค้ดสมัยใหม่ปล่อยเทเลเมทรีอยู่แล้วบางส่วน สิ่งนั้นช่วยได้ แต่ไม่พอ

OTEL แบบเนทีฟเก่งในการตอบคำถามอย่าง:

เราส่งคำขอไปกี่ครั้ง?
เซสชันนี้มีต้นทุนเท่าไหร่?
span และ trace อยู่ตรงไหน?
เวลาแฝงพุ่งขึ้นหรือไม่?

แต่มันแย่กว่ามากในการตอบคำถามอย่าง:

agent พึ่งพา MCP เซิร์ฟเวอร์ตัวไหน?
ความล้มเหลวนี้เกิดใน Bash, เครื่องมือไฟล์ในตัว หรือการเรียก MCP?
skill ตัวไหนที่ทำงานจริง?
เอเจนต์ย่อยประเภทไหนที่ถูกส่งงานไป?
เซสชันนี้กำลังทำงานที่มีประโยชน์ หรือแค่วนซ้ำอยู่กับที่?

คำถามกลุ่มที่สองนั้นอยู่ใกล้ hook มากกว่า trace

แต่ในทางกลับกันก็จริงเช่นกัน: คำถามด้านประสิทธิภาพที่สำคัญที่สุดบางข้ออยู่ใกล้ trace มากกว่า hook

ถ้าคุณอยากรู้ว่าเวลาแฝงสะสมอยู่ตรงไหนจริงๆ span ไหนที่ช้า หรือเซสชันเผาเวลาไปกับการเรียกโมเดลหรือการรันเครื่องมือ คุณต้องการข้อมูล trace เช่นเดียวกับ semantic อีเวนต์

สถาปัตยกรรมที่เราเลือกใช้

เรารันเส้นทางเทเลเมทรีสองเส้นทางคู่ขนานกัน

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

การแยกนั้นตั้งใจ

มันยังไม่สมมาตรด้วย Claude Code ให้อินเทอร์เฟซ hook ตลอดวงจรชีวิตที่หลากหลายกว่ามาก Codex ให้ OTEL แบบเนทีฟพร้อมอินเทอร์เฟซ notify ดังนั้นเรานอร์มัลไลซ์อีเวนต์การจบเทิร์นที่มีข้อมูลน้อยกว่าให้เข้ากับ schema ล็อกเดียวกัน แทนที่จะแสร้งว่าทั้งสองรันไทม์เปิดเผยการควบคุมแบบเดียวกัน

OTEL แบบเนทีฟ ให้สตรีมพื้นฐาน: ล็อกและ trace จากรันไทม์เอง บวกกับเมตริกในจุดที่รันไทม์ปล่อยจริง

Hook และ notify อีเวนต์ ให้ชั้น semantic: สิ่งอย่าง PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated และ metadata ที่จำแนกแล้ว ซึ่งเราสนใจจริงๆ เมื่อดีบักพฤติกรรม agent Claude Code ให้สตรีมอีเวนต์ที่หลากหลายกว่าตรงนี้ Codex ให้สตรีมที่นอร์มัลไลซ์แล้วซึ่งมีข้อมูลน้อยกว่าแต่ยังมีประโยชน์

เหตุใด Hook จึงมีอยู่เลย

hook pipeline ของเราเสริมอีเวนต์ก่อนที่มันจะไปถึง Loki

แทนที่จะบอกแค่ว่า “เครื่องมือหนึ่งทำงาน” เราจำแนกอีเวนต์ให้อยู่ในฟิลด์อย่าง:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: MCP แบ็กเอนด์ตัวไหนที่จัดการการเรียกนี้
bash_cli: กลุ่มคำสั่ง shell
subagent_type: ผู้เชี่ยวชาญประเภทไหนที่ถูกส่งงานไป
agent_tool: แหล่งที่มาคือ Claude Code หรือ Codex

นั่นหมายความว่าเราถามคำถามที่สำคัญในทางปฏิบัติได้:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

ฟิลด์เหล่านั้นไม่ใช่แค่ของประดับ มันคือความแตกต่างระหว่าง “agent รู้สึกช้า” กับ “agent ใช้เวลาสิบนาทีล่าสุดไปกับงาน git ที่หนัก shell และมีอัตราความล้มเหลวของเครื่องมือสูง”

รายละเอียดการอิมพลีเมนต์หนึ่งที่ดูแปลกกว่าที่มันเป็น: Loki สตรีมที่ใช้ร่วมกันยังคงใช้ service_name="claude-code-hooks" เป็นเลเบล แม้ว่าอีเวนต์จะมาจาก Codex ก็ตาม การแบ่งจริงระหว่างรันไทม์เกิดขึ้นที่ agent_tool

เหตุใด Alloy จึงอยู่ตรงกลาง

Grafana Alloy ไม่ใช่แค่ตัวส่งต่อในการตั้งค่านี้ มันคือขอบเขตนโยบาย

เราชี้สตรีม OTEL แบบเนทีฟจาก Claude Code และ Codex ไปยัง Alloy พร็อกซีในเครื่องที่ localhost:4318 แล้วปล่อยให้ Alloy ทำความสะอาด payload ก่อนส่งต่อไปยัง Grafana Cloud

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

session_id
prompt_id
จำนวน token
ระยะเวลา
ก้อนพารามิเตอร์ของเครื่องมือ

ถ้าคุณทำดัชนีทุกอย่าง จำนวนเลเบลจะพุ่งสูงจนสร้างปัญหาในการทำงาน

ดังนั้น Alloy ทำสามอย่างให้เรา:

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

แนวคิดสำคัญนั้นเรียบง่าย: สังเกตให้มากขึ้น ทำดัชนีให้น้อยลง

เหตุใด Hook สตรีมจึงข้าม Alloy

hook สตรีมถูกจัดรูปแบบให้ Loki อยู่แล้ว

เมื่อถึงเวลาที่ send_event.py ส่งอีเวนต์ เราตัดสินใจไปแล้วว่าฟิลด์ไหนควรได้รับการปฏิบัติแบบเลเบล และฟิลด์ไหนควรอยู่ในเนื้อหา JSON ที่มีโครงสร้าง สตรีมนั้นไปตรงยังเกตเวย์ OTLP ของ Grafana Cloud แทนที่จะผ่าน Alloy อีกรอบ

ดังนั้นระบบจึงมีการแบ่งงานที่ชัดเจน:

Alloy จัดระเบียบสตรีม OTEL แบบเนทีฟที่ยังไม่ผ่านการปรับแต่ง
การเสริม hook ทำให้ semantic อีเวนต์ค้นหาได้

สิ่งนี้ทำให้สถาปัตยกรรมเรียบง่ายกว่าการพยายามบังคับทุกอย่างให้ผ่านเส้นทางเดียว

แดชบอร์ดแสดงอะไรจริงๆ

ภาพหน้าจอด้านล่างมาจากหนึ่งในแดชบอร์ด observability เบื้องหลังเวิร์กโฟลว์ agent ของเรา มันไม่ใช่ benchmark และตัวเลขเป็นแค่ภาพ ณ ช่วงเวลาหนึ่ง ประเด็นคือรูปทรงของข้อมูล: ฟีดกิจกรรม, การเรียกเครื่องมือ, ความล้มเหลว, พรอมต์ และการแยกตาม agent, เครื่องมือในตัว, การใช้ MCP, คำสั่ง shell และ skill

ส่วนที่มีประโยชน์คือแดชบอร์ดนี้อยู่บน Grafana สแตกเดียวกับ agent เทเลเมทรีที่เหลือ เราสามารถกรองตาม agent ต้นทางและกลุ่มเครื่องมือ และดูข้อมูลข้ามรันไทม์โดยไม่ต้องคิดค้นเรื่องราว observability ที่ต่างกันสำหรับแต่ละระบบ

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

เหตุใด Trace จึงสำคัญกว่าที่เห็นในตอนแรก

ล็อกบอกเราว่าเกิดงานประเภทไหน Trace บอกเราว่างานนั้นคลี่คลายไปตามเวลาอย่างไร

ความแตกต่างนั้นสำคัญในระบบ agent เพราะคำว่า “ช้า” นั้นทื่อเกินกว่าจะมีประโยชน์

trace สามารถบอกเราได้ว่าปัญหานั้นมาจาก:

เวลาแฝงของโมเดล
เวลาการรันเครื่องมือ
การลองซ้ำซ้ำๆ
การโต้ตอบ MCP หนึ่งครั้งที่แพงเป็นพิเศษ
งานเล็กๆ จำนวนมากที่สะสมเวลาไว้ที่ดูไม่เป็นอันตรายเมื่อมองแยกกัน

ในทางปฏิบัติเราใช้ hook สตรีมและ Tempo trace ร่วมกัน

ล็อกจาก hook ตอบว่า: เกิดอะไรขึ้น?
Trace ตอบว่า: เวลาหายไปไหน?

การผสมผสานนี้คือสิ่งที่เปลี่ยน observability จากแดชบอร์ดให้กลายเป็นคำอธิบาย

Codex เข้ามาตรงไหน

Codex เป็นส่วนหนึ่งของสแตกเดียวกัน แต่ไม่เหมือนกับ Claude Code เสียทีเดียว

สำหรับ Codex เราเชื่อมสองส่วน:

OTEL แบบเนทีฟจาก Codex เข้าสู่ Alloy
notify webhook เข้าสู่ codex_notify.py ซึ่งแมปการจบเทิร์นให้เข้ากับ Loki schema เดียวกับที่เราใช้กับ hook อีเวนต์

นั่นทำให้เรามีตัวกรองรวมอย่าง agent_tool="codex-cli" ภายในสตรีมล็อกเดียวกัน

ข้อแม้ที่ตรงไปตรงมา: payload notify ของ Codex ในตอนนี้บางกว่า payload hook ของ Claude Code เพราะมันไม่ใช่อินเทอร์เฟซการผสานรวมแบบเดียวกัน ในระบบของเราวันนี้ การจบเทิร์นของ Codex สามารถถูกนอร์มัลไลซ์ให้เข้ากับ schema ที่ใช้ร่วมกันได้ แต่การดึงข้อมูลระดับเครื่องมือ ทีละตัวยังคงดีกว่าใน OTEL สตรีมแบบเนทีฟ มากกว่าใน notify บริดจ์

เราไม่ได้ยกข้อจำกัดนี้มาเป็นข้อแก้ตัว มันคือประเด็นของบทความนี้ ระบบ observability จริงถูกประกอบขึ้นจากสัญญาณที่ไม่สมบูรณ์แบบ

Grafana ผ่าน MCP เปลี่ยนเกม

การเปลี่ยนแปลงที่ใหญ่กว่าคือ Grafana ไม่ได้เป็นแค่สถานที่ที่มนุษย์เข้าไปดูในเบราว์เซอร์อีกต่อไป

ในรีโพนี้เรายังเปิด Grafana ผ่าน MCP ด้วย นั่นหมายความว่า agent สามารถคิวรี Loki, Prometheus และ Tempo ได้โดยตรง แทนที่จะรอให้มนุษย์ตรวจแดชบอร์ดด้วยมือก่อน

นั่นเปลี่ยน observability ให้กลายเป็นข้อมูลนำเข้าที่ช่วยขับเคลื่อนเวิร์กโฟลว์

agent สามารถถามได้ว่า:

กลุ่มเครื่องมือไหนล้มเหลวมากที่สุดในชั่วโมงที่ผ่านมา?
MCP เซิร์ฟเวอร์ตัวไหนครองเซสชันนี้?
การเปลี่ยนแปลงล่าสุดลดความล้มเหลวของเครื่องมือลงจริงหรือแค่ย้ายงานไปยังเส้นทางที่หนัก shell มากขึ้นด้วยความผิดพลาดแบบเดิม?
trace ไหนแสดงเวลาแฝงสูงสุดหรือการลองซ้ำซ้ำๆ?

เมื่อคุณมีสิ่งนั้นแล้ว คุณก็ใกล้เข้าไปยังลูปการปรับปรุงตัวเองมาก

จากแดชบอร์ดสู่ลูปป้อนกลับ

นี่คือส่วนที่เราพบว่าน่าสนใจที่สุด

เมื่อ observability สแตกค้นหาได้จากชั้น agent แล้ว เทเลเมทรีจะหยุดเป็นเครื่องมือรายงานที่รอให้คนเข้ามาดู และกลายเป็นสัญญาณควบคุม

ลูปหน้าตาแบบนี้:

กิจกรรมของ agent ปล่อย trace, เมตริก และล็อกจาก hook ที่เสริมแล้ว
Grafana เก็บหลักฐานไว้ใน Loki, Tempo และ Prometheus ในจุดที่มีเมตริก
agent คิวรีหลักฐานนั้นผ่าน Grafana MCP
ระบบระบุส่วนผสมเครื่องมือที่ไม่ดี skill ที่เปราะบาง การจัดเส้นทางที่อ่อนแอ หรือเวิร์กโฟลว์ที่หนัก shell ซึ่งยังคงก่อความผิดพลาดที่หลีกเลี่ยงได้
agent หรือผู้ควบคุมปรับพรอมต์, การตั้งค่าของ agent, คำอธิบาย skill, กฎการจัดเส้นทาง หรือสิทธิ์เข้าถึงเครื่องมือ
เซสชันถัดไปสร้างรูปทรงเทเลเมทรีใหม่ และวงจรก็ทำซ้ำ

นั่นคือวิธีที่คุณเคลื่อนจาก “แดชบอร์ดที่น่าสนใจ” ไปสู่ “ระบบปรับปรุงที่วัดผลได้”

เป้าหมายไม่ใช่การเพิ่มการใช้เครื่องมือประเภทเดียวให้สูงสุด แต่คือการลงเอยที่ส่วนผสมที่เหมาะสมของ CLI, เครื่องมือในตัว, การเรียก MCP และ skill สำหรับงานที่กำลังทำอยู่จริง

สิ่งนี้ช่วยให้เราตอบอะไรได้

เมื่อทั้งสองรันไทม์ลงเอยใน Grafana สแตกเดียวกัน เราตอบคำถามเชิงปฏิบัติการได้เร็วขึ้นมาก:

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

สิ่งนี้มีประโยชน์เป็นพิเศษในเวิร์กโฟลว์แบบหลาย agent ที่คำว่า “agent กำลังยุ่งอยู่” แทบไม่บอกอะไรคุณเลย

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

ถ้า MCP เซิร์ฟเวอร์ตัวหนึ่งครองการเรียกทั้งหมด นั่นอาจเป็นสถาปัตยกรรมที่ดี หรือเป็นสัญญาณว่าส่วนอื่นทั้งหมดเป็นส่วนเกินที่ไม่มีประโยชน์

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

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

ถ้า skill หนึ่งทำงานตลอดเวลาแต่ไม่ได้ปรับปรุงผลลัพธ์ นั่นคือสัญญาณของพรอมต์หรือการจัดเส้นทาง

บทเรียนที่แท้จริง

บทเรียนที่ลึกกว่านี้คือ agent observability ต้องการทั้ง เทเลเมทรีรันไทม์ และ เทเลเมทรีเวิร์กโฟลว์

เทเลเมทรีรันไทม์บอกคุณว่าระบบทำอะไร

เทเลเมทรีเวิร์กโฟลว์บอกคุณว่า agent คิดว่าตัวเองกำลังทำอะไร

เราต้องการทั้งสองอย่าง

ถ้าคุณเก็บแค่ trace และตัวนับ คุณจะพลาดชั้น semantic ถ้าคุณเก็บแค่ hook อีเวนต์ คุณจะพลาดเวลาแฝง, span และภาพรวมรันไทม์

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

การผสมผสานนี้คือสิ่งที่ทำให้ระบบอธิบายได้พอที่จะควบคุม และปรับได้พอที่จะปรับปรุง

สิ่งที่ยังไม่สมบูรณ์แบบ

ยังมีบางส่วนที่ต้องปรับปรุง

hook อีเวนต์ไม่ทุกตัวรวมข้อมูลระยะเวลาและ token ที่เราต้องการ
มุมมองด้านการจับเวลาที่ดีที่สุดบางส่วนยังคงมาจาก Tempo trace ไม่ใช่ล็อกจาก hook
Codex ในวันนี้มี semantic น้อยกว่า Claude Code ในสตรีมอีเวนต์ที่เสริมข้อมูลแล้ว
ภาพหน้าจอแดชบอร์ดเป็นหน้าจอที่ใช้ในการปฏิบัติงานจริง ไม่ใช่ผลงานการตลาดที่ขัดเกลาแล้ว

ประเด็นสุดท้ายนั้นตั้งใจ เราอยากแสดงแผงเครื่องมือจริงมากกว่าจะแสร้งว่าระบบ agent อธิบายตัวเองได้อย่างน่าอัศจรรย์

เหตุใดสิ่งนี้จึงสำคัญสำหรับ Maguyva

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

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

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

ถ้าคุณกำลังสร้างเวิร์กโฟลว์ agent อย่างจริงจัง observability ไม่ใช่โครงสร้างพื้นฐานที่เลือกได้ มันคือส่วนหนึ่งของผลิตภัณฑ์

ขุดค้นและปิดวงจร: การเปลี่ยนแปลงกลายเป็นความทรงจำองค์กรได้อย่างไร

Tue, 03 Feb 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (กุมภาพันธ์ 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

ทุกทีมวิศวกรรมเผชิญความท้าทายเดียวกัน: การเปลี่ยนแปลงเกิดขึ้นตลอดเวลา แต่ เหตุผล เบื้องหลังการเปลี่ยนแปลงเหล่านั้นหายไป หกเดือนต่อมา มีคนถามว่า “ทำไมเราถึงเลือกใช้ DuckDB สำหรับสเตจของไปป์ไลน์” และคำตอบอยู่ในหัวของคนที่ตัดสินใจนั้นเท่านั้น — ถ้าเขายังอยู่

เราสร้างเวิร์กโฟลว์การขุดค้นที่ปิดวงจรนี้ การเปลี่ยนแปลงไหลผ่าน git commit ถูกประมวลผลโดย pipeline การขุดค้นของเรา กลายเป็นรายการบันทึกการเปลี่ยนแปลงที่มีโครงสร้างและบันทึกการตัดสินใจเชิงสถาปัตยกรรม แล้วป้อนกลับเข้าสู่ AI agent ของเราผ่านคำสั่ง CLI ผลลัพธ์คือ: ความทรงจำองค์กรที่ทั้งมนุษย์และ AI เข้าถึงได้

ปัญหา: การตัดสินใจระเหยหายไป

พิจารณาสถานการณ์ทั่วไป นักพัฒนา commit ว่า:

feat(canonical): add DuckDB runtime for pipeline stages

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

เธรด Slack (น่าจะถูกลบไปแล้ว)
ความทรงจำของใครบางคน (ที่กำลังจางหายแน่นอน)
คอมเมนต์ในโค้ด (บางทีถ้าคุณโชคดี)

สามเดือนต่อมา สมาชิกทีมใหม่ถามว่า “ฉันควรใช้ DuckDB หรือ SQLite สำหรับสเตจใหม่นี้” หากไม่มีความทรงจำองค์กร พวกเขาจะต้องเริ่มคิดวิธีแก้ปัญหาเดิมตั้งแต่ต้น หรือเลือกอย่างไม่สอดคล้องกัน

วงจร: จาก Commit สู่บริบท

เวิร์กโฟลว์การขุดค้นของเราแปลงประวัติ git ให้เป็นความรู้ที่ค้นหาได้:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

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

การขุดค้นทำงานอย่างไร

ขั้นที่ 1: ซิงค์ดัชนี

uv run orkestra mine sync

คำสั่งนี้สแกนประวัติ git และสร้างดัชนีของ commit ทั้งหมด มันดึงสัญญาณเชิงโครงสร้างจากแต่ละ commit:

ประเภท conventional commit (feat, fix, chore, docs)
ขอบเขต (แพ็กเกจหรือพื้นที่ไหน)
เครื่องหมาย breaking change
ไฟล์ที่ถูกแตะและเมตริกความซับซ้อน

ขั้นที่ 2: ตรวจสอบสถานะความครอบคลุม

uv run orkestra mine status

นี่คือสถานะปัจจุบันของเรา:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

commit 15,637 รายการได้รับการประมวลผลแล้ว 476 รายการกลายเป็นการตัดสินใจเชิงสถาปัตยกรรม 6,799 รายการกลายเป็นรายการบันทึกการเปลี่ยนแปลง ทุก commit ถูกจำแนกแล้ว

ขั้นที่ 3: รับตัวเลือกเพื่อรีวิว

uv run orkestra mine candidates --limit 50 --full

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

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

สัญญาณช่วยชี้แนวทางการจำแนก: is_releasable_type: true บ่งบอกว่านี่ควรปรากฏในบันทึกการเปลี่ยนแปลง จำนวนบรรทัดที่เพิ่มขึ้นมากและไฟล์โครงสร้างพื้นฐานบ่งบอกว่ามันอาจเป็นการตัดสินใจเชิงสถาปัตยกรรมด้วย

ขั้นที่ 4: จำแนก Commit

สองเส้นทางแยกจากกันที่นี่: รายการบันทึกการเปลี่ยนแปลงและการตัดสินใจเชิงสถาปัตยกรรม

สำหรับรายการบันทึกการเปลี่ยนแปลง:

uv run orkestra mine classify abc123 --changelog added

สิ่งนี้บันทึกว่า commit abc123 ควรปรากฏในบันทึกการเปลี่ยนแปลงภายใต้หมวด “Added”

สำหรับการตัดสินใจเชิงสถาปัตยกรรม:

ก่อนอื่น รับ ID การตัดสินใจจริง:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

จากนั้นจำแนกด้วย ID การตัดสินใจ:

uv run orkestra mine classify abc123 --decision DEC-PL-143

สิ่งนี้เชื่อมโยง commit เข้ากับบันทึกการตัดสินใจที่จะถูกสร้างหรืออัปเดต

สำหรับการประมวลผลเป็นชุด (สิ่งที่เราทำจริงๆ):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

รูปแบบ JSONL รองรับทั้งสองโดเมนในรอบเดียว:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

ขั้นที่ 5: เรนเดอร์ผลลัพธ์

uv run orkestra registry changelog render --package <pkg>

สิ่งนี้สร้างไฟล์ CHANGELOG.md ต่อแพ็กเกจ จาก ledger บันทึกการเปลี่ยนแปลง เป็นไฟล์ที่สร้างจากข้อมูลต้นทาง — ลบมันแล้วมันจะสร้างขึ้นใหม่ได้อย่างสมบูรณ์จาก ledger ต้นทาง

โครงสร้างบันทึกการตัดสินใจ

การตัดสินใจที่ดึงออกมากลายเป็นไฟล์ YAML ที่มี metadata อันหลากหลาย:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

ทุกการตัดสินใจเชื่อมโยงกลับไปยัง commit ต้นทาง ทุกการตัดสินใจระบุว่าไฟล์ไหนได้รับผลกระทบ ความสัมพันธ์ระหว่างการตัดสินใจถูกทำให้ชัดเจน

การผสานรวมกับ CLI: การคิวรีความทรงจำองค์กร

นี่คือจุดที่วงจรปิดลง agent สามารถคิวรีการตัดสินใจผ่าน CLI ได้:

# Search by topic
uv run orkestra registry decisions search --query "retry"

คืนการตัดสินใจเกี่ยวกับตรรกะการลองซ้ำ, การจัดการข้อผิดพลาด, รูปแบบการกู้คืน

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

คืนบันทึกการตัดสินใจฉบับสมบูรณ์พร้อมบริบท เหตุผล และผลกระทบ

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

แสดงว่าการเลือกเชิงสถาปัตยกรรมใดถูกทำล่าสุด

Agent ใช้สิ่งนี้อย่างไร

คำสั่งพื้นฐานของออร์เคสเตรเตอร์ของเรารวมถึง:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

เมื่อ agent ถูกขอให้นำสิ่งที่เกี่ยวข้องกับ DuckDB ไปใช้งานจริง มันสามารถตรวจสอบก่อนได้ว่า:

uv run orkestra registry decisions search --query "DuckDB"

และค้นพบ DEC-PL-142 เรียนรู้ว่า:

ทำไมเราถึงเลือก DuckDB (บริบท)
ใช้มันอย่างถูกต้องอย่างไร (agent_guidance)
ไฟล์ไหนที่ต้องดู (files)
การตัดสินใจที่เกี่ยวข้องมีอะไรบ้าง (related)

agent ไม่ต้องเริ่มคิดวิธีแก้ปัญหาเดิมตั้งแต่ต้น มันต่อยอดจากรูปแบบที่วางไว้แล้ว

แบบทดสอบสามคำถาม

ไม่ใช่ทุก commit ที่สมควรมีบันทึกการตัดสินใจ เราใช้แบบทดสอบสามคำถามเพื่อคัดกรอง:

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

หาก commit ตอบว่า “ใช่” อย่างน้อยหนึ่งในคำถามเหล่านี้ มันคือตัวเลือกสำหรับการดึงการตัดสินใจ อัตราทั่วไปของเรา: 1-4 การตัดสินใจต่อ 100 commit (ประมาณ 1-4%)

สำหรับรายการบันทึกการเปลี่ยนแปลง เกณฑ์ต่ำกว่า: การเปลี่ยนแปลงที่ผู้ใช้เห็น (ฟีเจอร์, การแก้ไข, การปรับปรุง) จะถูกบันทึกไว้ งานภายใน, การอัปเดตเอกสาร และการรีแฟกเตอร์มักถูกข้ามไป อัตราทั่วไปของเรา: 30-50 รายการบันทึกการเปลี่ยนแปลง ต่อ 100 commit

การจัดเก็บข้อมูล: Ledger แบบเพิ่มได้อย่างเดียว

ระบบการขุดค้นใช้ ledger แบบ JSONL ที่เพิ่มได้อย่างเดียวเพื่อการทำงานหลาย agent โดยไม่มีความขัดแย้ง:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

รูปแบบ JSONL พร้อม merge=union ใน .gitattributes หมายความว่า agent หลายตัวสามารถจำแนก commit พร้อมกันได้โดยไม่มีความขัดแย้งจากการผสาน แต่ละบรรทัดเป็นอิสระจากกัน

เกณฑ์การตรวจสอบ

ก่อนทุกเซสชันการขุดค้น เรารันการตรวจสอบ:

uv run orkestra mine validate --quick

สิ่งนี้ตรวจสอบ:

ความถูกต้องของรูปแบบ SHA
การปฏิบัติตามรูปแบบ ID การตัดสินใจ
ไม่มีรายการซ้ำสำหรับ SHA เดียวกัน
การตัดสินใจที่ถูกอ้างอิงมีอยู่จริง

หลังจากการจำแนก เราตรวจสอบอีกครั้งก่อน commit การเปลี่ยนแปลง

เหตุใดสิ่งนี้จึงสำคัญ

ลูปป้อนกลับที่เราสร้างขึ้นแก้ปัญหาหลายอย่าง:

สำหรับสมาชิกทีมใหม่: แทนที่จะถามว่า “ทำไมเราถึงทำ X” พวกเขาสามารถค้นหารีจิสทรีการตัดสินใจได้ บริบทถูกเก็บรักษาไว้

สำหรับ AI agent: พวกมันไม่ได้ทำงานในสุญญากาศ พวกมันสามารถคิวรีความรู้องค์กรก่อนให้คำแนะนำได้ เมื่อถูกขอให้เพิ่ม pipeline stage ใหม่ พวกมันสามารถค้นพบรูปแบบ DuckDB และทำตามได้

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

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

สำหรับการออนบอร์ด: agent ใหม่รับช่วงบริบททั้งหมดของโค้ดเบส พวกมันไม่ได้แค่เห็นโค้ด — พวกมันเห็นการตัดสินใจที่หล่อหลอมมันด้วย

สถานะปัจจุบัน

ณ วันนี้:

15,637 commit ผ่านการประมวลผลใน pipeline
476 การตัดสินใจเชิงสถาปัตยกรรม ถูกดึงและบันทึกแล้ว
6,799 รายการบันทึกการเปลี่ยนแปลง ถูกบันทึกแล้ว
ความครอบคลุม 100% ข้ามทั้งสองโดเมน

ทุก commit ตั้งแต่เราเริ่มต้นถูกจำแนกแล้ว ความทรงจำองค์กรสมบูรณ์และค้นหาได้

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

หากคุณต้องการนำสิ่งที่คล้ายกันไปใช้จริง:

เริ่มด้วย conventional commit pipeline การขุดค้นทำงานได้ดีที่สุดเมื่อ commit มีคำนำหน้าที่มีโครงสร้าง (feat:, fix:, chore:)
นิยามโดเมนของคุณ เราใช้โดเมนอย่าง pipeline, agent-design, observability, data-modeling สิ่งเหล่านี้จัดระเบียบการตัดสินใจตามพื้นที่
สร้างนิสัยการจำแนก การขุดค้นทำงานได้เมื่อทีมจำแนก commit อย่างสม่ำเสมอ การประมวลผลเป็นชุดด้วยความช่วยเหลือของ LLM ช่วยให้ขยายสเกลได้
ทำให้คิวรีการตัดสินใจได้ คุณค่าจะทวีคูณเมื่อ agent สามารถค้นหาการตัดสินใจผ่าน CLI ได้ จัดโครงสร้างผลลัพธ์ของคุณให้เครื่องอ่านได้
ปิดวงจร การตัดสินใจควรมีอิทธิพลต่องานในอนาคต รวมการอ้างอิงการตัดสินใจไว้ในคำสั่งของ agent และรายการตรวจสอบการรีวิวโค้ด

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

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

การขุดค้น Skill: จาก 3,500 รายการที่เข้าข่ายสู่ 466 ความสามารถ

Tue, 27 Jan 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (มกราคม 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

ปัญหา Skill 3,500 รายการ

เมื่อเราเริ่มสร้างระบบประสาน agent เราเจอความท้าทายที่น่าสนใจ: มี skill ที่เป็นไปได้หลายพันรายการกระจายอยู่ทั่วระบบนิเวศ AI GitHub รีโพซิทอรี, เอกสาร vendor, โปรเจกต์ชุมชน, รูปแบบภายใน — skill มีอยู่ทุกที่ แต่อันไหนสำคัญ? อันไหนทำงานได้จริง? และคุณจะดูแลคลัง skill ที่สอดคล้องกันซึ่ง agent ใช้งานได้จริงได้อย่างไร?

คำตอบของเรา: ลูปการขุดค้นและนำเข้าอย่างเป็นระบบ

ตัวเลขวันนี้

เพียงสามเดือนเศษหลังจาก Anthropic เปิดตัว Agent Skills เมื่อวันที่ 16 ตุลาคม 2025 นี่คือจุดที่เรายืนอยู่เมื่อบทความนี้เผยแพร่ เมื่อวันที่ 27 มกราคม 2026:

เมตริก	จำนวน
รายการที่เข้าข่ายที่ระบุแล้ว	3,500+
Skill ที่รับเข้าใช้งาน	466
Skill จาก Vendor	373
Skill ภายใน	93
Vendor ที่ใช้งานอยู่	25+
Token เฉลี่ยต่อ Skill	2,834
เครื่องมือที่ถูกอ้างอิง	89
แท็กที่ไม่ซ้ำกัน	635

เราได้รีวิว skill รายการที่เข้าข่ายไปแล้วกว่า 3,500 รายการ เรารับเข้าใช้งาน 466 รายการ นั่นคืออัตราการรับเข้า 13% — และเราตั้งใจคัดเลือกอย่างเข้มงวดเช่นนี้

ระบบชั้นความรู้

skill แต่ละตัวมีคุณภาพและขอบเขตต่างกัน เราจัดระเบียบพวกมันเป็นห้าชั้นความรู้ (K0-K4) แต่ละชั้นแทนขอบเขตการใช้งานที่ต่างกัน:

K0: รากฐาน (สากล)

Skill ที่ agent ทุกตัวควรมี สิ่งเหล่านี้แทนความสามารถ “นักคิดที่ดี” ที่ทำงานได้ทุกที่

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Skill ระดับ K0 พกพาได้ไปยังโปรเจกต์ใดก็ตาม โดเมนใดก็ตาม สแตกใดก็ตาม พวกมันเข้ารหัสรูปแบบทางปัญญาสากล

K1: อัตลักษณ์ (สาขาวิชาชีพ)

Skill แบบ “วิศวกรที่ดี” หรือ “นักวิจัยที่ดี” ที่ใช้ได้ข้ามโปรเจกต์ภายในสาขาวิชาชีพหนึ่ง

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: โดเมน (ความเชี่ยวชาญเฉพาะเรื่อง)

Skill แบบ “ผู้เชี่ยวชาญฐานข้อมูลที่ดี” หรือ “วิศวกรความปลอดภัยที่ดี” ที่พกพาได้ภายในสาขาหนึ่ง

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (เทคโนโลยี)

Skill แบบ “ผู้ใช้ Supabase ที่ดี” หรือ “นักพัฒนา Cloudflare ที่ดี” สำหรับเทคโนโลยีสแตกเฉพาะ

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: โปรเจกต์ (องค์กร)

Skill เฉพาะสำหรับองค์กรและเวิร์กโฟลว์ของเรา

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

ลูปการขุดค้น

เฟส 1: การค้นพบ

Skill มาจากทุกที่:

คลัง Vendor: AWS, Anthropic, Cloudflare, Supabase และผู้ร่วมพัฒนาจากชุมชนเผยแพร่ชุด skill เราติดตามแหล่งต้นทาง vendor มากกว่า 25 แหล่ง

โปรเจกต์ชุมชน: GitHub เต็มไปด้วยเทมเพลตของ Claude Code, รูปแบบ agent และคำนิยามเวิร์กโฟลว์

รูปแบบภายใน: เมื่อทีมของเราแก้ปัญหา รูปแบบก็ปรากฏขึ้น สิ่งเหล่านี้ถูกทำให้เป็นทางการเป็น skill

การขุดเอกสาร: เอกสารทางเทคนิคมักมี skill โดยนัยอยู่ — ขั้นตอน, รายการตรวจสอบ, ต้นไม้การตัดสินใจ

การค้นพบเป็นไปอย่างต่อเนื่อง เราใช้ skill แบ็กล็อกเพื่อติดตามรายการที่เข้าข่ายก่อนการประเมินอย่างเป็นทางการ

เฟส 2: การประเมิน

skill ทุกตัวที่เข้าข่ายได้รับการประเมินด้วยเกณฑ์เดียวกัน:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

เกณฑ์ผลิตภัณฑ์ทั้งห้าต้องผ่านทั้งหมด นี่คือเหตุผลที่รายการที่เข้าข่าย 87% ถูกปฏิเสธ

จากนั้นskill ทุกตัวที่เข้าข่ายจะผ่านการรีวิวความน่าเชื่อถือแยกต่างหาก เราไม่ถือว่า vendor รีโพซิทอรีที่เป็นทางการ ผู้ดูแลชุมชนที่มีชื่อเสียง และ GitHub รีโพสุ่มๆ เป็นแหล่งความจริงที่เท่าเทียมกัน

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

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

การวิเคราะห์ช่องว่าง: ก่อนรับเข้าใช้งาน เราค้นหาในรีจิสทรีของเรา:

uv run orkestra skills search "<capability>"

ถ้าเรามีมันอยู่แล้ว เราก็ไม่ต้องการมันอีก ถ้าเรามีอะไรที่ใกล้เคียง เราอาจรวมมันเข้าด้วยกันแทนที่จะรับเข้าใช้งาน

การให้คะแนนความลึกและมาตรฐาน: เรายังให้คะแนนว่ารายการที่เข้าข่ายใช้โมเดล agent-skill อย่างเต็มที่แค่ไหน SKILL.md เดี่ยวๆ ยังคงมีประโยชน์ได้ แต่ skill ที่ลึกกว่าจะมีคุณค่ามากกว่าเมื่อมันแยกคำสั่งออกจากเอกสารอ้างอิง, สคริปต์ และทรัพยากร ในแบบที่ agentskills.io สนับสนุน

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

ดาว GitHub สามารถยกระดับคะแนนความน่าเชื่อถือได้เล็กน้อย แต่มันไม่เคยช่วยกู้ skill ที่ตื้นหรือไม่ปลอดภัยได้ รีโพที่มีดาวสูงพร้อม SKILL.md ที่คลุมเครือหนึ่งอันและสคริปต์ที่ตรวจสอบการทำงานได้ยาก จะได้คะแนนต่ำกว่ารีโพที่เล็กกว่าซึ่งมีคำอธิบายที่แม่นยำ references/ ที่คัดสรรมาอย่างดี และสคริปต์ช่วยงานขนาดเล็กที่รับผิดชอบงานเดียวที่ใช้ประโยชน์จากความสามารถของ skill เต็มรูปแบบจริงๆ

การวิเคราะห์เชิงโครงสร้าง: เราตรวจสอบคุณภาพ skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

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

เฟส 3: การนำเข้า

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

การปรับเปลี่ยนตอนรับเข้าใช้งาน:

การนอร์มัลไลซ์ Metadata: ทุก skill ได้รับ frontmatter schema ของเรา
การกำหนดชั้น K: skill ถูกวางในชั้นความรู้ที่เหมาะสม
การเสริมแท็ก: มีการเพิ่มแท็กเพื่อการค้นพบ
การประกาศเครื่องมือ: เครื่องมือที่อนุญาตถูกประกาศอย่างชัดเจน
การจัดวางส่วน: เนื้อหาถูกจัดโครงสร้างใหม่ให้ตรงกับเทมเพลตของเรา

skill YAML ทั่วไปหลังการนำเข้า:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

เฟส 4: การกำหนดขอบเขต

Skill ถูกกำหนดให้กับขอบเขต — หมวดหมู่ที่ตัดสินว่า agent ตัวไหนโหลด skill ตัวไหน:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

agent ประกาศขอบเขตของตัวเอง และ skill จะถูกกำหนดโดยอัตโนมัติ:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

เฟส 5: การสร้างไฟล์ที่ใช้งานได้จริง

Skill ไม่ได้อาศัยอยู่เป็น YAML ในโปรดักชัน พวกมันถูกเรนเดอร์เป็นไฟล์ SKILL.md ที่ Claude Code โหลดได้:

uv run orkestra sync

คำสั่งนี้:

อ่านคำนิยาม skill YAML ทั้งหมด
เรนเดอร์พวกมันผ่าน Jinja เทมเพลต
เขียนไฟล์ SKILL.md ไปยัง .claude/skills/
จัดระเบียบตามชั้น K (foundations/, identities/, domains/, stacks/, project/)

โครงสร้างผลลัพธ์สุดท้าย:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

รูปแบบขอบเขตแบบแฝง

หนึ่งในรูปแบบที่ทรงพลังที่สุดของเราคือ skill แบบ “รับเข้าแต่ไม่โหลด” เราเรียกสิ่งเหล่านี้ว่าขอบเขตแฝง

พิจารณา skill การคำนวณทางวิทยาศาสตร์จาก k-dense-scientific รีโพซิทอรี เรารับเข้าใช้งาน skill มากกว่า 120 รายการครอบคลุมชีวสารสนเทศศาสตร์, เคมี, การประมวลผลควอนตัม และสารสนเทศศาสตร์คลินิก แต่ agent ส่วนใหญ่ของเราไม่ต้องการการจำลองการเข้าจับกันของโมเลกุล หรือการวิเคราะห์การแสดงออกของยีน

แทนที่จะโหลด skill ทั้ง 120 รายการเข้าไปในทุก agent (ทำให้หน้าต่างบริบทบวม) เรา:

รับเข้าใช้งาน skill พร้อมขอบเขตที่ระบุ (เช่น bioinformatics)
ปล่อยให้มันแฝงอยู่ — ลงทะเบียนแต่ไม่โหลด
เปิดใช้งาน เฉพาะเมื่อ agent ประกาศขอบเขตนั้น

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

รูปแบบนี้ทำให้เรามี skill 466 รายการในรีจิสทรี ในขณะที่ agent ทั่วไปโหลดเพียง 40-60 รายการที่เกี่ยวข้อง

ประเภท Skill

Skill มาในสามรูปแบบทางปัญญา:

เวิร์กโฟลว์

ขั้นตอนตามลำดับ: “1. ทำ X, 2. จากนั้นทำ Y, 3. สุดท้ายทำ Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

วินัย

ข้อจำกัดเชิงพฤติกรรม: “ทำ X เสมอ”, “ห้ามทำ Y”, “ควรเลือก Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

รายการตรวจสอบ

เกณฑ์การตรวจสอบ: “ยืนยัน X”, “ตรวจสอบ Y”, “เช็ค Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

เกณฑ์คุณภาพ

ทุก skill ต้องผ่านการตรวจสอบก่อนถูกปล่อยออกมา:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

คำอธิบายต้องมี 50-400 ตัวอักษรพร้อมวลีกระตุ้น (“ใช้เมื่อ…”, “เมื่อคุณต้องการ…”) เพื่อให้ Claude Code รู้ว่าจะแนะนำมันเมื่อไหร่

เราตรวจสอบอย่างต่อเนื่อง:

uv run orkestra validate --show-warnings

ระบบนิเวศ Vendor

skill 373 รายการจาก vendor ของเรามาจาก:

ผู้ให้บริการ	Skill	โดเมน
AWS Agent	19	บริการคลาวด์
Anthropic	12	การสร้างเอกสาร
Cloudflare	8	การประมวลผลแบบเอดจ์
Supabase	5	ฐานข้อมูล
k-dense	100+	การคำนวณทางวิทยาศาสตร์
silvainfm	4	วิทยาการข้อมูล
Java Developer Kit	45+	Spring/Java
Vercel	1	ระบบอัตโนมัติของเบราว์เซอร์

แต่ละแหล่งต้นทาง vendor ถูกประกาศใน metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

เมื่อ orkestra sync รัน skill ของ vendor จะถูก symlink เข้าไปใน .claude/skills/vendor/ พร้อม namespace ของผู้ให้บริการ

สิ่งที่เราเรียนรู้

ความเลือกสรรคุ้มค่า มันน่าดึงดูดที่จะรับเข้าใช้งานทุกอย่างที่ดูมีประโยชน์ แต่ skill แต่ละอันมีต้นทุนเป็น token ด้วยค่าเฉลี่ย 2,834 token ต่อ skill การโหลดสิ่งที่เกินจำเป็นทำให้บริบทเต็มอย่างรวดเร็ว อัตราการรับเข้าใช้งาน 13% ของเราทำให้ agent ยังคงกระชับ

โครงสร้างเปิดให้ค้นพบ ระบบชั้น K ไม่ใช่แค่การจัดระเบียบ — มันคือเรื่องของการพกพาได้ skill ระดับ K0 นำกลับมาใช้ที่ไหนก็ได้ skill ระดับ K4 ตั้งใจให้เจาะจงเฉพาะโปรเจกต์ ความชัดเจนนี้ช่วยทั้งมนุษย์และ agent หาสิ่งที่ต้องการได้

ขอบเขตแฝงขยายสเกลได้ คุณสามารถรับเข้าใช้งาน skill หลายร้อยรายการโดยไม่ต้องโหลดทั้งหมด ขอบเขตให้คุณสร้างรีจิสทรีที่ครอบคลุม ในขณะที่ยังรักษาหน้าต่างบริบทของ agent แต่ละตัวให้จัดการได้

การปรับเปลี่ยนตอนรับเข้าใช้งานเป็นสิ่งจำเป็น skill vendor แบบดิบแทบไม่เคยเข้ากับระบบของคุณเลย กระบวนการนำเข้า — การเพิ่ม metadata, การกำหนดชั้น, การเสริมแท็ก — ทำให้ skill ภายนอกทำงานภายในได้

การขุดค้นเป็นไปอย่างต่อเนื่อง ตัวเลข 3,500 ยังคงเติบโตต่อไป vendor รีโพใหม่ปรากฏขึ้น รูปแบบชุมชนเกิดขึ้น เวิร์กโฟลว์ภายในตกผลึก ลูปไม่เคยหยุด

ต่อไปคืออะไร

เรากำลังทำงานเกี่ยวกับการปรับปรุงหลายอย่าง:

การตรวจจับช่องว่างอัตโนมัติ: แจ้งเตือนเมื่อความล้มเหลวทั่วไปของ agent สามารถแก้ไขได้ด้วย skill ที่ยังไม่ได้รับเข้าใช้งาน
เวิร์กโฟลว์การเลิกใช้ skill: กระบวนการที่เป็นทางการสำหรับการปลดระวาง skill ที่ถูกแทนที่หรือไม่ได้ใช้
การพึ่งพาข้าม Skill: การประกาศข้อกำหนดเบื้องต้นของ skill อย่างชัดเจน
การวิเคราะห์การใช้งาน: ติดตามว่า skill ไหนที่ agent เรียกใช้จริงเทียบกับแค่โหลด

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

นั่นคือเรื่องราวว่า 3,500 กลายเป็น 466 ได้อย่างไร ไม่ใช่ด้วยการเพิกเฉยต่อ 3,000 รายการ — แต่ด้วยการประเมินอย่างเป็นระบบและรับเข้าใช้งานเฉพาะสิ่งที่ใช้ได้ผล

อยากเห็นระบบ skill ทำงานจริงไหม ดูที่ uv run orkestra skills list เพื่อสำรวจรีจิสทรีปัจจุบันของเรา

การเปิดเผยแบบค่อยเป็นค่อยไป: หน้าต่าง CLI สู่ระบบ Agent

Tue, 20 Jan 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (มกราคม 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

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

คำตอบคือการเปิดเผยแบบค่อยเป็นค่อยไป: อินเทอร์เฟซแบบเป็นชั้นที่เผยความซับซ้อนพอดีกับที่คุณต้องการ ในเวลาที่คุณต้องการมันพอดี

ปัญหาการมองไม่เห็นการทำงานภายใน

ระบบประสาน agent สมัยใหม่อาจมี:

agent ผู้เชี่ยวชาญ 40+ ตัว แต่ละตัวมีความสามารถที่แตกต่างกัน
skill 700+ รายการครอบคลุมทั้งระบบอัตโนมัติภายในและการผสานรวมกับ vendor
การตัดสินใจเชิงสถาปัตยกรรม 470+ รายการที่หล่อหลอมพฤติกรรม
เซิร์ฟเวอร์เครื่องมือ MCP หลายสิบตัวที่ให้ความสามารถภายนอก

ความซับซ้อนนี้ตั้งใจ agent ต้องการเข้าถึงบริบทที่หลากหลาย — ความรู้โดเมน, โค้ดอินเทลลิเจนซ์, สคีมาฐานข้อมูล — เพื่อตัดสินใจได้ดี แต่ความหลากหลายเดียวกันนั้นสร้างปัญหาการมองเห็น

คุณจะรู้ได้อย่างไรว่า agent ตัวไหนจัดการการย้ายฐานข้อมูล? การตัดสินใจอะไรหล่อหลอมพฤติกรรมการจัดอันดับของระบบค้นหา? เครื่องมือใดที่ที่ปรึกษาสถาปัตยกรรมเข้าถึงได้?

หากไม่มีการเข้าถึงที่มีโครงสร้าง คุณจะเหลือแค่การอ่านซอร์สโค้ดหรือหวังว่าเอกสารจะเป็นปัจจุบัน

การเปิดเผยแบบค่อยเป็นค่อยไปในฐานะสถาปัตยกรรม

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

สำหรับระบบ agent สิ่งนี้แปลงเป็นคำสั่ง CLI ที่ระดับความลึกเพิ่มขึ้น:

ระดับ	คำสั่ง	คำถามที่ตอบ
1	`orkestra system status`	ทุกอย่างสุขภาพดีไหม?
2	`orkestra agents list`	agent อะไรมีอยู่?
3	`orkestra agents info <name>`	agent นี้ทำอะไร?
4	`orkestra decisions search`	ทำไมมันถึงทำงานแบบนี้?
5	เครื่องมือ MCP ของ Maguyva	แสดงโค้ดให้ฉันดู

แต่ละระดับตอบคำถามติดตามผลตามธรรมชาติ คุณแทบไม่ต้องกระโดดตรงไปที่ระดับ 5 เลย

ระดับ 1: สุขภาพระบบ

คำถามแรกมักเป็น: ทุกอย่างทำงานอยู่ไหม?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

หนึ่งคำสั่ง สี่ตัวเลข พอที่จะรู้ว่าระบบถูกตั้งค่าและรีจิสทรีถูกเติมข้อมูลแล้ว

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

ระดับ 2: รายการ Agent

เมื่อคุณรู้ว่าระบบสุขภาพดีแล้ว คำถามถัดไปคือ: มีอะไรบ้าง?

$ orkestra agents list

สิ่งนี้คืนข้อมูลที่มีโครงสร้าง — ชื่อ agent, คำอธิบาย, โมเดลที่กำหนดให้เลือกใช้, ความครอบคลุมโดเมน ผลลัพธ์เป็น JSON โดยค่าเริ่มต้น ทำให้ง่ายต่อการต่อเข้ากับ jq เพื่อกรอง:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

ต้องการ agent ที่จัดการงานฐานข้อมูล? คำสั่ง search ช่วยจำกัดให้แคบลง:

$ orkestra agents search "database"

สิ่งนี้สแกนชื่อ, คำอธิบาย และความสามารถ คุณเจอผู้เชี่ยวชาญที่ถูกต้องโดยไม่ต้องอ่านคำนิยาม agent 40 ตัว

ระดับ 3: เจาะลึก Agent

เจอ agent ที่ดูเกี่ยวข้องแล้ว? คำสั่ง info เผยทุกอย่าง:

$ orkestra agents info architecture-advisor

ผลลัพธ์รวมถึง:

Metadata: ชื่อ, หมวดหมู่, โมเดลที่กำหนดให้เลือกใช้, คำอธิบาย
Domains: โดเมนความรู้ไหนที่ agent นี้ครอบคลุม
Identity: ลักษณะนิสัย (architect, strategist, knowledge-architect)
คู่มือเครื่องมือ: เอกสารเครื่องมือไหนที่ถูกเพิ่มเข้าในบริบท
เครื่องมือ: รายการเครื่องมือ MCP ทั้งหมดที่ agent นี้เข้าถึงได้

นี่คือตัวอย่างสิ่งที่คุณเห็น:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

สิ่งนี้บอกคุณอย่างชัดเจนว่า agent ทำอะไรได้บ้าง ไม่ต้องดูซอร์สโค้ด

ระดับ 4: สืบย้อนที่มาของการตัดสินใจ

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

$ orkestra decisions search "agent"

สิ่งนี้คืนการตัดสินใจเชิงสถาปัตยกรรมที่ตรงกัน:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

แต่ละการตัดสินใจมีที่มาที่ไปครบถ้วน — ตัดสินใจเมื่อใด ทำไม ข้อแลกเปลี่ยนอะไรถูกพิจารณา commit ไหนนำไปใช้จริง:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

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

ระดับ 5: โค้ดอินเทลลิเจนซ์ โดยตรง

เมื่อคุณต้องการเห็นการอิมพลีเมนต์จริง — ไม่ใช่แค่ metadata เกี่ยวกับมัน — เครื่องมือ MCP ของ Maguyva ให้การเข้าถึงโดยตรง

จากภายในเซสชัน agent:

mcp__maguyva__intelligent_search
  query: "agent context loading"

สิ่งนี้ส่งผ่านอัตโนมัติข้าม semantic, text และ AST search เพื่อหาโค้ดที่เกี่ยวข้องสำหรับสัญลักษณ์เฉพาะ:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

สำหรับการวิเคราะห์ dependency:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

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

การค้นหาแบบรวมข้ามรีจิสทรี

บางครั้งคุณไม่รู้ว่ารีจิสทรีไหนมีคำตอบ การค้นหาแบบรวมครอบคลุมทุกอย่าง:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 ผลลัพธ์ที่ตรงกันจากรีจิสทรีทั้งห้า สรุปบอกคุณว่าจะเจาะลึกที่ไหน ลบ --summary ออกเพื่อผลลัพธ์ที่ละเอียด หรือเพิ่ม --limit 5 เพื่อให้ผลลัพธ์จัดการได้ง่าย

เหตุใดสิ่งนี้จึงสำคัญ

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

การดีบักกลายเป็นเรื่องจัดการได้ เมื่อ agent ตัดสินใจอย่างไม่คาดคิด คุณไม่ต้อง grep ผ่านล็อก คุณตรวจสอบเครื่องมือที่มันเข้าถึงได้ (agents info) การตัดสินใจอะไรหล่อหลอมพฤติกรรมของมัน (decisions search) และตามรอยการอิมพลีเมนต์ถ้าจำเป็น (intelligent_search)

การออนบอร์ดเร็วขึ้น สมาชิกทีมใหม่ไม่ต้องอ่านโค้ดเบสทั้งหมด พวกเขาเริ่มด้วย system status สำรวจด้วย agents list และเจาะลึกเฉพาะเมื่อพวกเขาเจอบางอย่างที่ไม่เข้าใจ

เอกสารทันสมัยอยู่เสมอ เพราะ CLI อ่านจากรีจิสทรีเดียวกับที่ตั้งค่า agent ผลลัพธ์จึงถูกต้องเสมอ ไม่มีการเบี่ยงเบนระหว่างสิ่งที่เอกสารบอกกับสิ่งที่ระบบทำ

CLI ในฐานะอินเทอร์เฟซ

เราสามารถสร้างแดชบอร์ดเว็บได้ เราสามารถเขียนเอกสารอย่างละเอียดได้ แต่แทนที่จะทำอย่างนั้น เราสร้าง CLI ที่อ่านจากแหล่งความจริง

CLI มีข้อได้เปรียบ:

ประกอบได้: ต่อผลลัพธ์ผ่าน jq ผสานรวมกับสคริปต์
เขียนสคริปต์ได้: ทำการตรวจสอบอัตโนมัติ สร้างรายงาน
เร็ว: ไม่มีการโหลดหน้า ไม่มีขั้นตอน authentication
แม่นยำ: อ่านการตั้งค่าจริง ไม่ใช่ตัวแทนที่แคชไว้

สำหรับระบบที่ความถูกต้องสำคัญกว่าความสวยงาม CLI ชนะ

การสร้างการเปิดเผยแบบค่อยเป็นค่อยไปของคุณเอง

หากคุณกำลังสร้างระบบ agent ให้พิจารณาว่าผู้ใช้จะตรวจสอบมันอย่างไร:

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

แต่ละชั้นตอบคำถามติดตามผล สร้างพวกมันตามลำดับความถี่ — ผู้ใช้ส่วนใหญ่หยุดที่ชั้น 2 หรือ 3 มีเพียงผู้ใช้ขั้นสูงเท่านั้นที่ไปถึงชั้น 5

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

Ground Truths: ยึดโยง AI Agent ไว้กับความเป็นจริง

Tue, 13 Jan 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (มกราคม 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

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

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

เราต้องการสิ่งที่ชัดเจนกว่านั้น สิ่งที่ไม่สามารถถูกมองข้ามหรือตีความผิดได้ สิ่งที่จะยึดโยง agent ไว้กับความเป็นจริงที่ตรวจสอบได้

เราเรียกมันว่า Ground Truths

Ground Truth คืออะไร?

ground truth คือข้อความข้อเท็จจริงที่ชัดเจนและมีเวอร์ชัน ซึ่ง agent ต้องเคารพ มันไม่ใช่เอกสาร มันไม่ใช่คอมเมนต์ มันคือเอนทิตีชั้นหนึ่งในระบบที่มี:

ตัวระบุที่ไม่ซ้ำกัน (เช่น GT-MAG-015 หรือ GT-MAG-036)
สถานะวงจรชีวิต (current, tentative หรือ deprecated)
ขอบเขต (ทั้งแพลตฟอร์ม, เฉพาะแพ็กเกจ หรือผูกกับโดเมน)
หลักฐาน (path ของไฟล์, URL หรือการอ้างอิงที่พิสูจน์ข้อความนั้น)
คำแนะนำสำหรับ agent (คำสั่ง do/avoid ที่ชัดเจน)

นี่คือตัวอย่างจากแพลตฟอร์มโค้ดอินเทลลิเจนซ์ Maguyva ของเรา:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

นี่ไม่ใช่ร้อยแก้ว มันคือสัญญา เมื่อ agent พบ ground truth นี้ มันจะรู้ว่า:

ค่าเริ่มต้นเป็นแบบกำหนดแน่นอน (ผลลัพธ์ว่างเปล่า ไม่ใช่การเดาจากการจับคู่โดยประมาณ)
มีพารามิเตอร์เฉพาะ (find_similar, exact_match) พร้อมพฤติกรรมที่นิยามไว้
มีหลักฐานอยู่ในไฟล์เฉพาะที่สามารถตรวจสอบได้
ข้อความถูกยืนยันในวันที่ระบุ

โครงสร้างของ Ground Truth รีจิสทรี

ground truth อาศัยอยู่ใน YAML รีจิสทรี ภายใต้ ai_assets/reference/ground_truths.yaml แต่ละแพ็กเกจ หรือโดเมนสามารถมีรีจิสทรีของตัวเองได้ โครงสร้างคือ:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

รีจิสทรีประกอบด้วย metadata เกี่ยวกับตัวชุดเอง, การตั้งค่าการเรนเดอร์สำหรับสร้างเอกสาร และข้อความเอง แต่ละข้อความปฏิบัติตาม schema ที่เข้มงวดซึ่งตรวจสอบด้วย Pydantic โมเดล:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Agent เข้าถึง Ground Truth ได้อย่างไร

ground truth ถูกเปิดผ่านหลายช่องทาง:

1. เอกสารที่เรนเดอร์แล้ว

คำสั่ง orkestra sync แปลง YAML รีจิสทรีให้เป็น markdown ที่อ่านได้:

uv run orkestra sync

สิ่งนี้สร้างไฟล์ GROUND_TRUTHS.md ที่ถูกรวมเข้าในบริบทของ agent ผลลัพธ์ที่เรนเดอร์แล้วจะจัดกลุ่มข้อความตามสถานะและหมวดหมู่:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. การค้นหาด้วย CLI

agent ที่เข้าถึง shell ได้สามารถค้นหา ground truth แบบโปรแกรมได้:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

ฟังก์ชันค้นหาให้คะแนนการจับคู่ข้ามหลายฟิลด์ด้วยน้ำหนักถ่วง:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. การประกอบบริบท

เมื่อ agent ถูกเรนเดอร์จากคำนิยาม YAML บริบทของมันสามารถอ้างอิง ground truth รีจิสทรีได้:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

สิ่งนี้ทำให้แน่ใจว่า ground truth ที่เกี่ยวข้องถูกโหลดก่อนที่ agent จะเริ่มทำงาน

หมวดหมู่ของ Ground Truth

เมื่อพิจารณารีจิสทรีทั้งหมดของเรา ground truth จะรวมกลุ่มเป็นรูปแบบหลายอย่าง:

หลักการผลิตภัณฑ์

ข้อจำกัดว่าผลิตภัณฑ์คืออะไรและไม่ใช่อะไร:

“Maguyva เป็นแบบอ่านอย่างเดียวต่อรีโพซิทอรีของผู้ใช้ สินทรัพย์เดียวที่สร้างขึ้นใหม่ไม่ได้คือแคชเอ็มเบดดิ้งที่ต้องชำระเงิน” (GT-MAG-001)

ขอบเขตสถาปัตยกรรม

ความรับผิดชอบอยู่ที่ไหนและเพราะเหตุใด:

“ขอบเขตระหว่าง pipeline กับ Maguyva ตั้งใจไว้แบบนี้: pipeline นำกลับมาใช้ใหม่ได้, Maguyva เก็บตรรกะเฉพาะโค้ด และ CQRS แยกการเขียนของสเตจออกจากการอ่านของเซิร์ฟเวอร์” (GT-MAG-006)

กฎป้องกันการหลอน

คำสั่งที่ชัดเจนซึ่งรักษาให้สัญญาเครื่องมือเป็นแบบกำหนดแน่นอนแทนการอนุมาน:

“การจับคู่สัญลักษณ์แบบโดยประมาณเป็นแบบเลือกเปิดใช้เองผ่าน find_similar=true พฤติกรรมเริ่มต้นคืนผลลัพธ์ว่างเปล่าสำหรับสัญลักษณ์ที่ไม่มีอยู่จริง exact_match=true บังคับให้จับคู่แบบเข้มงวดและปิดทางเลือกสำรองที่ใช้การจับคู่โดยประมาณทั้งหมด” (GT-MAG-015)

เกณฑ์คุณภาพ

มาตรฐานที่ต้องรักษาไว้:

“การเปลี่ยนแปลงโครงสร้างพื้นฐานที่ใช้ร่วมกัน (post_filters.py, ตัวดึงความสัมพันธ์, ตัวจัดการที่ใช้ร่วมกัน) ต้องได้รับการตรวจสอบกับ ทุก ภาษาที่รองรับผ่านการสร้าง full manifest ก่อน commit การตรวจสอบภาษาเดียวไม่เพียงพอสำหรับโค้ดที่ใช้ร่วมกัน” (GT-MAG-036)

รูปแบบโค้ด

ข้อกำหนดการอิมพลีเมนต์:

“ใช้ asyncio.to_thread() สำหรับงานที่หนัก CPU ในบริบท async รูปแบบ loop.run_in_executor() ที่เลิกใช้แล้วไม่ควรถูกใช้ในโค้ดใหม่” (GT-MAG-018)

วงจรชีวิตของ Ground Truth

ground truth ไม่คงที่ มันวิวัฒนาการผ่านวงจรชีวิตที่นิยามไว้:

Tentative

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

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current

ความจริงที่ยืนยันแล้วซึ่ง agent ต้องเคารพ หลักฐานได้รับการตรวจสอบแล้ว:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated

ความจริงที่ไม่ใช้แล้ว ถูกเก็บไว้เพื่ออ้างอิงทางประวัติศาสตร์พร้อมตัวชี้ไปยังสิ่งที่มาแทนที่:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

เหตุใดจึงไม่ใช้แค่เอกสาร?

เอกสารรับใช้จุดประสงค์ที่ต่างกัน มันอธิบาย มันสอน มันคลุมเครือได้ ใช้คำอย่าง “โดยทั่วไป” หรือ “มักจะ” ได้

ground truth คลุมเครือไม่ได้ มันคือการยืนยัน มันเป็นจริงหรือไม่เป็นจริง

พิจารณาความแตกต่าง:

เอกสาร: “API มักจะคืนผลลัพธ์ว่างเปล่าเมื่อไม่พบสัญลักษณ์ แม้ว่าการจับคู่แบบโดยประมาณอาจถูกเปิดใช้ในการตั้งค่าบางแบบ”

Ground Truth: “พฤติกรรมเริ่มต้นคืนผลลัพธ์ว่างเปล่าสำหรับสัญลักษณ์ที่ไม่มีอยู่จริง exact_match=true บังคับให้จับคู่แบบเข้มงวดและปิดทางเลือกสำรองที่ใช้การจับคู่โดยประมาณทั้งหมด”

อย่างแรกมีประโยชน์สำหรับมนุษย์ที่เรียนรู้ระบบ อย่างที่สองสามารถนำไปปฏิบัติได้สำหรับ agent ที่กำลังตัดสินใจ

คำแนะนำสำหรับ Agent: สิ่งที่ควรทำและควรหลีกเลี่ยง

ground truth บางอย่างมีคำแนะนำสำหรับ agent ที่ชัดเจน:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

สิ่งนี้ขจัดความคลุมเครือ agent ที่อ่านสิ่งนี้จะรู้ไม่เพียงแค่ว่าอะไรเป็นจริง แต่ยังรู้ว่าความจริงนั้นหมายความว่าต้องทำอะไร

การยืนยันและการบำรุงรักษา

ground truth ต้องการการบำรุงรักษา เราติดตาม:

last_verified: เวลาที่มีการยืนยันว่าข้อความยังคงเป็นจริง
evidence: ไฟล์ที่พิสูจน์ข้อความ (สามารถตรวจสอบว่ามีอยู่จริงได้)
source: ความจริงมาจากไหน (การตรวจสอบด้วย CLI, การรีวิวสถาปัตยกรรม, บทเรียนหลังเหตุการณ์)

ground truth ที่มีวันยืนยันเก่าหรือลิงก์หลักฐานที่เสีย คือสัญญาณให้ตรวจสอบ ข้อเท็จจริงนั้นอาจยังใช้ได้และต้องยืนยันซ้ำ หรืออาจเปลี่ยนไปแล้วและต้องอัปเดต

ตัวอย่างจริงจากโปรดักชัน

ขอบเขตความปลอดภัย

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

ground truth นี้ป้องกัน “การปรับปรุงความปลอดภัย” ที่เข้าใจผิดประเภทหนึ่ง ซึ่งจะทำลายผลิตภัณฑ์

ความแม่นยำ ณ เวลาแตกโครงสร้าง

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

สิ่งนี้มาจากประสบการณ์ที่เจ็บปวด agent เคยแพตช์แพ็กภาษาที่ล้มเหลวด้วยการเพิ่มตัวกรองที่ทำงานเฉพาะในวาลิเดเตอร์ที่ทำให้ชุดทดสอบดูเขียวขึ้น ในขณะที่ตัวสกัด Maguyva ตัวจริงยังคงปล่อย edge ที่ผิดอยู่ กฎนี้บังคับให้การแก้ไขกลับไปยังเส้นทางจริง: การตั้งค่า YAML, คิวรี หรือตัวจัดการ

การกรองหลายชั้น

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

สิ่งนี้ป้องกัน agent จากการเพิ่มตัวกรองในจุดที่ผิด ซึ่งเป็นความผิดพลาดทั่วไปที่เคยทำให้ความแม่นยำถดถอย

การผสานรวมกับระบบออร์เคสเตรชัน

ground truth คือชั้นหนึ่งของระบบบริบทที่กว้างกว่า:

การตัดสินใจเชิงสถาปัตยกรรม (ADR) - บันทึกว่าทำไมเราจึงเลือกวิธี A แทน B
Ground Truths - ระบุว่าอะไรเป็นจริงแน่นอนในตอนนี้
รูปแบบโดเมน - อธิบายวิธีทำสิ่งต่างๆ ให้ถูกต้อง
Anti-Patterns - อธิบายสิ่งที่ควรหลีกเลี่ยงและเพราะเหตุใด

agent ที่ทำงานในระบบสามารถเข้าถึงทั้งสี่อย่างได้ ground truth มอบจุดยึดข้อเท็จจริง ในขณะที่การตัดสินใจอธิบายประวัติศาสตร์ รูปแบบชี้นำการอิมพลีเมนต์ และ Anti-Patterns เตือนถึงข้อผิดพลาด

การวัดผลกระทบ

นับตั้งแต่นำ ground truth มาใช้ เราได้สังเกตเห็น:

วงจร “แก้ไขสิ่งที่หลอนขึ้นมา” น้อยลง
การตัดสินใจของ agent มั่นใจมากขึ้นเมื่อข้อเท็จจริงชัดเจน
การรีวิว PR ที่ดีขึ้นเพราะความคาดหวังชัดเจน
เวลาออนบอร์ด agent ใหม่ลดลง (รวมถึงสมาชิกทีมที่เป็นมนุษย์)

การลงทุนในการบำรุงรักษา ground truth คุ้มค่าในการลดการดีบักและทำให้ขอบเขตระบบชัดเจนขึ้น

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

ในการเพิ่ม ground truth ให้ระบบของคุณ:

สร้าง ground_truths.yaml ในไดเรกทอรี ai_assets/reference/ ของแพ็กเกจของคุณ
นิยาม metadata และการตั้งค่าการเรนเดอร์
เพิ่มข้อความตาม schema
รัน uv run orkestra sync เพื่อสร้างเอกสาร
รวมรีจิสทรีเข้าในการประกอบบริบทของ agent

เริ่มด้วยข้อเท็จจริงที่ก่อความสับสนมากที่สุด หรือข้อจำกัดที่ถูกละเมิดบ่อยที่สุด นั่นคือ ground truth ที่มีคุณค่าสูงสุดของคุณ

บทสรุป

AI agent จะหลอน นั่นคือธรรมชาติของมัน แต่เราสามารถสร้างสภาพแวดล้อมที่การหลอนถูกจำกัดได้ ที่ข้อเท็จจริงบางอย่างต่อรองไม่ได้ ที่ agent สามารถตรวจสอบสมมติฐานของตัวเองกับความเป็นจริงที่ยืนยันแล้วได้

ground truth ไม่ใช่ทางออกที่สมบูรณ์ มันต้องการการบำรุงรักษา มันสามารถล้าสมัยได้ มันเพิ่มภาระให้กระบวนการพัฒนา

แต่มันมอบสิ่งที่มีคุณค่า: คำศัพท์ร่วมของข้อเท็จจริงที่ทั้งมนุษย์และ agent สามารถไว้วางใจได้ ในโลกที่ agent เข้ามามีส่วนร่วมในการพัฒนาซอฟต์แวร์มากขึ้นเรื่อยๆ รากฐานที่ใช้ร่วมกันนั้นกลายเป็นสิ่งจำเป็น

ทางเลือกอื่นคือวงจรไม่รู้จบของ agent ที่ทำผิดพลาดอย่างมั่นใจ และมนุษย์คอยแก้ไข ground truth ทำลายวงจรนั้นด้วยการทำให้การแก้ไขชัดเจนและคงทน

agent ของคุณสมควรรู้ว่าอะไรเป็นจริง บอกพวกมัน

Orkestra: การประสานงาน AI Agent ในระดับใหญ่

Tue, 06 Jan 2026 00:00:00 GMT

ตัวเลขในบทความนี้สะท้อนระบบ ณ วันที่เผยแพร่ (มกราคม 2026) ดูหน้าทีมของเราสำหรับตัวเลขปัจจุบัน

เมื่อเราเริ่มสร้างด้วย Claude Code เราเจอปัญหาที่ทุกทีมที่ใช้ผู้ช่วยเขียนโค้ด AI ต้องเจอในที่สุด: agent ตัวเดียวทำทุกอย่างได้ดีไม่ได้

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

เราจึงสร้าง Orkestra

Orkestra คืออะไร?

Orkestra คือระบบประสานงาน agent สำหรับ Claude Code และเครื่องมือเขียนโค้ด AI ที่คล้ายกัน มันประสานงาน agent เฉพาะทางหลายตัว แต่ละตัวมีความเชี่ยวชาญที่แตกต่างกัน ภายใต้ออร์เคสเตรเตอร์เดียวที่จัดสรรงานไปยังผู้เชี่ยวชาญที่ถูกต้อง

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

ตัวเลขบอกเรื่องราว:

องค์ประกอบ	จำนวน
Agent ผู้เชี่ยวชาญ	46
Skill ที่นำกลับมาใช้ใหม่ได้	466
ต้นแบบ Identity	27
Mindset	11
สไตล์การสื่อสาร	10
โดเมนความรู้	21

ระบบตัวละคร: D&D สำหรับ Agent

ข้อมูลเชิงลึกหลักเบื้องหลัง Orkestra คือพฤติกรรมของ agent เกิดขึ้นจากพื้นฐานที่ประกอบกันได้สามอย่าง:

Identity นิยาม สิ่งที่ agent เป็น สถาปนิกออกแบบโครงสร้างระบบ นักดีบักตามรอยความล้มเหลวไปยังต้นตอ ผู้พิทักษ์ดูแลให้ปฏิบัติตามข้อกำหนดและรักษาขอบเขตความปลอดภัย เรามีต้นแบบ identity 27 แบบที่ผสมกันได้

Mindset นิยาม วิธีที่ agent คิด mindset เชิงวิเคราะห์ยึดการยืนยันไว้กับหลักฐานและวัดความไม่แน่นอน mindset ที่ตั้งข้อสงสัยอย่างมีเหตุผล ตั้งคำถามต่อสมมติฐานและหาหลักฐานที่หักล้าง mindset เชิงสำรวจโอบรับความคลุมเครือและลองหลายวิธี

Style นิยาม วิธีที่ agent สื่อสาร สไตล์เชิงเทคนิครวมค่าที่แน่นอนและอ้างอิงไฟล์เฉพาะ สไตล์กระชับตัดสิ่งฟุ่มเฟือยออกและนำด้วยคำตอบ สไตล์การทูตสร้างสมดุลระหว่างความซื่อสัตย์กับความมีไหวพริบ

agent หนึ่งผสมพื้นฐานเหล่านี้เข้าด้วยกัน:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

องค์ประกอบนี้สร้าง agent ที่ออกแบบระบบ (architect), เชื่อมโยงความรู้ข้ามโดเมน (knowledge-architect), กำหนดทิศทางเชิงกลยุทธ์ (strategist), คิดด้วยหลักฐานและข้อมูล (analytical) และสื่อสารโดยไม่มีสิ่งฟุ่มเฟือย (concise)

จุดเด่นคือจำนวนรูปแบบที่เกิดจากการผสมองค์ประกอบ identity 27 แบบ คูณด้วย mindset 11 แบบ คูณด้วยสไตล์ 10 แบบ ให้บุคลิกภาพ agent ที่เป็นไปได้เกือบ 3,000 แบบ แต่คุณนิยามเฉพาะการผสมที่สำคัญต่องานของคุณเท่านั้น

Skill: โมดูลความสามารถที่นำกลับมาใช้ใหม่ได้

Skill คือความรู้และเวิร์กโฟลว์ที่ agent สามารถเรียกใช้ได้ พวกมันทำตามระบบแบ่งชั้นตามขอบเขต:

ชั้น	ชื่อ	ขอบเขต	ตัวอย่าง
K0	Foundations	วิธีการสากล	วินัยแบบ test-first, การเสร็จงานตามหลักฐาน
K1	Identities	เวิร์กโฟลว์ตามบทบาท	มาตรฐานอินเทอร์เฟซ CLI, playbook ประสิทธิภาพ
K2	Domains	ความรู้เฉพาะโดเมน	รูปแบบการย้ายฐานข้อมูล, การตรวจสอบ authentication
K3	Stacks	เฉพาะเทคโนโลยี	การดีพลอย Cloudflare, การทำงานของ Supabase
K4	Project	เฉพาะโค้ดเบสนี้	เวิร์กโฟลว์และข้อตกลงเฉพาะโปรเจกต์

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

แต่ละ skill รวมถึง:

เงื่อนไขกระตุ้นที่ชัดเจน (“ใช้เมื่อย้าย schema ฐานข้อมูล”)
คำแนะนำทีละขั้นตอน
เครื่องมือที่อนุญาตสำหรับเวิร์กโฟลว์
เกณฑ์ความสำเร็จและเส้นทางการกู้คืนความล้มเหลว

skill 466 รายการในรีจิสทรีของเราครอบคลุมทุกอย่างตั้งแต่การแยก git worktree ไปจนถึงเวิร์กโฟลว์การวิจัยเว็บไปจนถึงการตรวจสอบสุขภาพการดีพลอย

เหตุใดออร์เคสเตรชันจึงสำคัญ

สถาปัตยกรรม agent เดี่ยวชนกำแพงอย่างรวดเร็ว:

บริบทเจือจาง หน้าต่างบริบท 200,000 token ฟังดูใหญ่จนกว่าคุณจะโหลด schema ฐานข้อมูล, เอกสาร API, test fixture และความรู้โดเมน ผู้เชี่ยวชาญสามารถทำงานกับบริบทที่เจาะจงได้

คำสั่งขัดแย้งกัน การบอก agent ให้ “ละเอียดถี่ถ้วนแต่รวดเร็ว” และ “ตรวจสอบทุกอย่างแต่อย่าทำเกินความจำเป็น” สร้างความตึงเครียด ผู้เชี่ยวชาญแก้ปัญหานี้ด้วยการมีขอบเขตที่ชัดเจน

ความลึกของความเชี่ยวชาญ agent ผู้รู้ทั่วไปรู้เล็กน้อยเกี่ยวกับทุกเรื่อง agent ผู้เชี่ยวชาญที่ประกอบด้วย identity และ skill ที่ถูกต้อง รู้โดเมนของตัวเองอย่างลึกซึ้ง

Orkestra ใช้การออร์เคสเตรชันแบบชั้นเดียว: ออร์เคสเตรเตอร์เดียวประสานผู้เชี่ยวชาญหลายตัว ผู้เชี่ยวชาญไม่สามารถสร้างผู้เชี่ยวชาญย่อยได้ สิ่งนี้ป้องกันการระเบิดของความซับซ้อน ในขณะที่ยังเปิดให้ทำงานคู่ขนานได้

ออร์เคสเตรเตอร์เข้าถึงความจุที่มีประสิทธิผลได้ 2.2 ล้าน token: หน้าต่างบริบท 200,000 ของตัวเอง บวกกับเอเจนต์ย่อยคู่ขนาน 10 ตัวที่มี 200,000 แต่ละตัว งานที่จะทำให้ agent เดี่ยวหมดแรงสามารถรันได้อย่างสบายๆ ทั่วทั้งทีม

Pipeline การเรนเดอร์

คำนิยาม agent อาศัยอยู่ใน YAML Claude Code อ่าน Markdown Orkestra เชื่อมช่องว่างนี้ด้วย pipeline การเรนเดอร์แบบกำหนดแน่นอน:

YAML Registries → Jinja Templates → .claude/agents/*.md

ผู้ควบคุมแก้ไข YAML ต้นทาง รัน orkestra sync Markdown ที่เรนเดอร์แล้วจะปรากฏใน .claude/agents/ Claude Code รับการเปลี่ยนแปลงนั้นไป

การแยกนี้รับใช้ผู้ใช้ที่แตกต่างกัน:

YAML ต้นทาง รวม metadata วงจรชีวิต, แท็ก, กฎการตรวจสอบ และหมายเหตุการเลิกใช้สำหรับเครื่องมือ
Markdown ที่เรนเดอร์แล้ว รวมเฉพาะสิ่งที่โมเดลต้องการ: คำอธิบาย, เครื่องมือ, skill และคำแนะนำเชิงพฤติกรรม

pipeline ประกอบ identity, mindset, style และ skill เข้าเป็นพรอมต์เดียวที่สอดคล้องกัน agent แบบ architect-analytical-concise จะได้พรอมต์ระบบที่ต่างจาก agent แบบ debugger-skeptical-technical มาก แม้ว่าพวกมันจะแชร์ skill พื้นฐานบางอย่างร่วมกันก็ตาม

ความรู้โดเมน: รูปแบบสี่ไฟล์

ทุกโดเมนความรู้ทำตามโครงสร้างที่สอดคล้องกัน:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

โครงสร้างนี้รับใช้การโหลดบริบทของ agent agent ที่ทำงานด้าน authentication โหลด authentication/patterns.md เพื่อคำแนะนำ และ authentication/anti-patterns.md เพื่อหลีกเลี่ยงข้อผิดพลาดที่รู้จักแล้ว ไฟล์เหล่านี้ถูกกำหนดขนาดให้เหมาะกับการโหลดบริบทอย่างมีประสิทธิภาพ: เจาะจงพอที่จะมีประโยชน์ ครอบคลุมพอที่จะน่าเชื่อถือ

เรารักษาโดเมนระดับบนสุด 21 โดเมน รวมถึงการวิเคราะห์ข้อมูล, authentication, data science, โครงสร้างพื้นฐาน, การเรียนรู้ของเครื่อง, ประสิทธิภาพ, ความปลอดภัย และอื่นๆ แต่ละโดเมนสามารถมีโดเมนย่อยเพื่อความละเอียดที่ลึกกว่าได้

Values: ระบบปฏิบัติการ

agent ทุกตัวแชร์ชั้นค่านิยมพื้นฐานที่นิยามว่าพวกมันทำงานอย่างไร:

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

แก้ที่ต้นตอ อย่าแพตช์รอบความล้มเหลว ถ้า pipeline ล้มเหลว ดีบัก pipeline ถ้า test ล้มเหลว แก้โค้ดหรือแก้ test

ยึดหลักฐาน ระบุการอ้างว่า “ยืนยันแล้ว” (พร้อม benchmark) หรือ “ประมาณการ” (พร้อมสมมติฐาน) รูปแบบที่ตรวจพบ ไม่เท่ากับปัญหาที่ยืนยันแล้ว

เศรษฐศาสตร์บริบท เครื่องมือ MCP มีต้นทุน 0.1% ของบริบท การอ่านไฟล์มีต้นทุน 2% ต่อครั้ง ใช้ความเชี่ยวชาญโดเมนก่อนสำรวจโค้ด

ค่านิยมเหล่านี้ถูกถ่ายทอดไปยังผู้เชี่ยวชาญทุกตัวผ่าน pipeline การเรนเดอร์ โครงสร้างการประกอบ agent ทำให้ไม่สามารถหลีกเลี่ยงค่านิยมเหล่านี้ได้

CLI: ชั้นควบคุม

Orkestra มาพร้อม CLI สำหรับจัดการระบบนิเวศ agent:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI คือแหล่งความจริงว่า agent อะไรมีอยู่ พวกมันมี skill อะไร และระบบสุขภาพดีหรือไม่ มันรันการตรวจสอบก่อนซิงค์เพื่อจับปัญหาแต่เนิ่นๆ

ข้อพิจารณาด้าน Open Source

เราสร้าง Orkestra เพื่อแก้ปัญหาของเราเอง: การประสาน AI agent ในระดับใหญ่สำหรับโค้ดเบสที่ซับซ้อน รูปแบบที่เราค้นพบไม่ได้เจาะจง แค่โดเมนของเรา

ระบบประกอบตัวละคร (identity + mindset + style) ใช้ได้กับทีมใดก็ตามที่นิยามบุคลิกภาพ agent

ระบบชั้น skill (K0-K4) มอบโมเดลทางความคิดสำหรับจัดระเบียบความสามารถที่นำกลับมาใช้ใหม่ได้ตามขอบเขต

รูปแบบ pipeline การเรนเดอร์ (YAML ต้นทาง + เทมเพลต + ไฟล์ที่สร้างขึ้น) แยกความรับผิดชอบระหว่างเครื่องมือกับการใช้งานของโมเดล

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

Orkestra จะกลายเป็น open source หรือไม่ขึ้นอยู่กับว่ารูปแบบเหล่านี้มีคุณค่าสำหรับคนอื่นที่สร้างด้วย Claude Code หรือไม่ หากคุณกำลังชนกำแพงที่เราอธิบาย สถาปัตยกรรมนี้อาจช่วยได้

สิ่งที่เราเรียนรู้

การสร้าง Orkestra สอนเราว่าออร์เคสเตรชันไม่ใช่เรื่องของการทำให้ agent ฉลาดขึ้น มันคือการทำให้พวกมันโฟกัสมากขึ้น

agent เดี่ยวที่มีคำสั่งสมบูรณ์แบบก็ยังหมดบริบทได้ agent เดี่ยวที่มี skill ทั้งหมดก็ยังสับสนว่าจะใช้อันไหน agent เดี่ยวที่พยายามเป็นทุกอย่าง สร้างผลลัพธ์ปานกลางในทุกที่

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

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

Orkestra ขับเคลื่อนระบบนิเวศ agent เบื้องหลัง Maguyva แพลตฟอร์มโค้ดอินเทลลิเจนซ์ของเรา อยากเรียนรู้เพิ่มเติมไหม ติดต่อทีมของเรา