SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor

Graft แผนผัง codebase สำหรับ coding agent ผ่าน MCP

Graft ใช้ tree-sitter วิเคราะห์ repository สร้างแผนผัง codebase แบบถาวร และให้ coding agent ค้นหาผ่าน MCP เพื่อลดการสำรวจโครงสร้างซ้ำในทุกเซสชัน

แผนผัง codebase สำหรับ coding agent คืออะไร

แผนผัง codebase สำหรับ coding agent คือดัชนีแบบถาวรของ repository ที่ agent ใช้สำหรับค้นหาข้อมูล แทนที่จะต้องไล่ค้นหา (grep) ใหม่ทั้งหมดตั้งแต่ต้นในทุกเซสชัน Graft เป็นการนำแนวคิดนี้ไปใช้งานจริงรูปแบบหนึ่ง โดยจะทำการวิเคราะห์โค้ดของคุณด้วย tree-sitter จากนั้นเขียนข้อมูลลงในโฟลเดอร์ที่ประกอบด้วยโหนด markdown ที่เชื่อมโยงกันและกราฟการเชื่อมต่อรายสัญลักษณ์ พร้อมทั้งให้บริการเครื่องมือสำหรับการดึงข้อมูลผ่าน MCP (model context protocol ซึ่งเป็นอินเทอร์เฟซมาตรฐานที่ coding agent ใช้เรียกใช้งานเครื่องมือภายนอก)

Graft ไม่ใช่ proxy และไม่ใช่ gateway ไม่มีสิ่งใดคั่นกลางระหว่าง agent ของคุณกับ model API แผนผังนี้เป็นเพียงโฟลเดอร์บนดิสก์ที่ agent อ่านข้อมูล ความแตกต่างนี้เป็นตัวกำหนดว่าคุณกำลังแก้ปัญหาใดอยู่: self-hosted token gateway จะทำหน้าที่วัดปริมาณและกำหนดเส้นทางคำขอที่คุณส่งออกไปอยู่แล้ว ในขณะที่แผนผังจะช่วยลดจำนวนคำขอที่คุณจำเป็นต้องส่งลง

เทคนิคนี้มีมาก่อนเครื่องมือนี้และจะยังคงอยู่ต่อไป ให้เรียนรู้เทคนิคก่อน แล้วจึงค่อยเรียนรู้กลไกการทำงานของมัน

เหตุใด Coding Agent จึงเสียค่า Context ไปกับการค้นหาโครงสร้างซ้ำๆ

ลองสังเกต Agent ขณะเริ่มทำงานใน Repository ที่มันเคยเห็นมาแล้วกว่า 50 ครั้ง มันจะแสดงรายการไดเรกทอรี ใช้ grep ค้นหาสัญลักษณ์ เปิดไฟล์ 3 ไฟล์เพื่อหาว่าไฟล์ไหนนิยามฟังก์ชันนั้นไว้ แล้วเปิดไฟล์ที่ 4 เพื่อดูว่าใครเรียกใช้ฟังก์ชันดังกล่าว สิ่งเหล่านี้ไม่ใช่เนื้องานจริง แต่มันคือการปรับตัว (orientation) ซึ่งคุณต้องจ่ายค่า input tokens ในทุกๆ เซสชัน

สาเหตุนั้นเรียบง่าย โมเดลไม่มีหน่วยความจำระหว่างเซสชัน ทุกสิ่งที่ Agent เรียนรู้เกี่ยวกับโครงสร้างโค้ดของคุณจะอยู่ใน context window ซึ่งจะถูกทิ้งไปเมื่อเซสชันสิ้นสุดลง ดังนั้นการค้นหาเดิมจึงเริ่มต้นจากศูนย์ใหม่ และคุณก็ต้องจ่ายเงินซ้ำอีกครั้ง Prompt caching ให้ส่วนลดเฉพาะกับ prefix ของ prompt ที่เหมือนกันซึ่งพบภายใน 5 นาทีล่าสุด หรือภายใน 1 ชั่วโมงโดยมีค่าใช้จ่ายเพิ่มเติม จึงไม่สามารถนำข้อมูลการสำรวจของเมื่อวานมาใช้ในเซสชันของวันนี้ได้ ใน Repository ขนาดใหญ่ ขั้นตอนการปรับตัวมีค่าใช้จ่ายสูงกว่าการแก้ไขโค้ดจริงเสียอีก เช่น ต้องเรียกใช้เครื่องมือ 10 ครั้งเพื่อระบุตำแหน่งโค้ด แต่ใช้เพียง 1 ครั้งเพื่อแก้ไข การปรับตัวเป็นเพียงครึ่งหนึ่งของค่าใช้จ่าย และการแก้ไขคืออีกครึ่งหนึ่ง นี่คือเหตุผลว่าทำไม ทักษะที่ควบคุมให้ Agent เปลี่ยนแปลงโค้ดน้อยที่สุดเท่าที่จำเป็น จึงควรใช้ควบคู่ไปกับการทำแผนที่ (map) แทนที่จะเลือกอย่างใดอย่างหนึ่ง

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

คุณอาจกำลังใช้งานเวอร์ชันที่ด้อยกว่านี้อยู่แล้ว ไฟล์ AGENTS.md ที่ระบุข้อตกลงในการเขียนโค้ดของคุณ ช่วยป้องกันไม่ให้ Agent ต้องมานั่งอนุมานข้อตกลงของคุณใหม่ทุกครั้ง ส่วนแผนที่ที่สร้างขึ้นโดยอัตโนมัติจะช่วยป้องกันไม่ให้มันต้องมานั่งอนุมานโครงสร้างโค้ดใหม่ สำหรับความแตกต่างนั้นขึ้นอยู่กับว่าใครเป็นผู้เขียน หากคุณเขียนไฟล์คำสั่งด้วยตัวเอง มันจะมีขนาดเล็ก แต่หากใช้ parser สร้างแผนที่ มันจะสามารถครอบคลุมไฟล์ได้นับหมื่นไฟล์ สำหรับรายละเอียดว่าในหนึ่งเซสชันงบประมาณถูกใช้ไปกับอะไรบ้าง วิธีที่ Claude Code จัดสรรการใช้ context window จะอธิบายการคำนวณส่วนนี้ไว้

สิ่งที่ Graft สร้างขึ้นจริง

ผลลัพธ์มี 2 ส่วน ทั้งหมดอยู่ภายใต้โฟลเดอร์ graft/ ที่รูทของ repository

ส่วนแรกคือ node graph ที่เขียนด้วย markdown แบบเชื่อมโยงกัน โดยหนึ่งไฟล์ต่อหนึ่งโหนด แต่ละโหนดจะเก็บสรุปเนื้อหาด้วยภาษาทั่วไป, "หัวใจสำคัญ" (crux) ของบรรทัดตรรกะที่ดึงมาจากซอร์สโค้ด, ไฟล์ซอร์สโค้ดต้นฉบับพร้อมค่า content hash, wikilinks แบบระบุประเภทที่เชื่อมไปยังโหนดอื่น (depends_on, part_of, uses, implements) และส่วนบันทึกย่อที่จะคงอยู่แม้มีการสร้างไฟล์ใหม่ เพื่อให้คุณสามารถบันทึกบริบทที่ตัว parser ไม่สามารถวิเคราะห์เองได้

ส่วนที่สองคือ graft/.graph/wiring.json ซึ่งเป็นโครงสร้างกราฟรายสัญลักษณ์ที่ tree-sitter สกัดออกมา ได้แก่ นิยาม (definitions), การอ้างอิง (references) และเส้นเชื่อมการเรียกใช้ (call edges) ระหว่างกัน

การแยกส่วนนี้มีความสำคัญเพราะมีเพียงครึ่งเดียวที่ต้องใช้โมเดล graft build เป็นการทำงานของ tree-sitter ล้วนๆ และไม่เคยเรียกใช้ LLM (large language model) จึงมีความแม่นยำแน่นอนและไม่มีค่าใช้จ่าย ส่วน graft build --deep จะเพิ่มส่วนสรุปที่เป็นข้อความและหัวใจสำคัญรายสัญลักษณ์ ซึ่งส่วนนี้คือการเรียกใช้โมเดลที่คุณต้องเสียค่าใช้จ่าย

การรองรับภาษาจะแบ่งเป็นระดับ ซึ่งระดับดังกล่าวจะบอกคุณว่าควรเชื่อถือ call graph มากน้อยเพียงใด สำหรับ TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift และ R จะได้การแก้ไขความสัมพันธ์ข้ามไฟล์แบบรับรู้ขอบเขต (scope-aware) ส่วน Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix และ Lua จะได้สัญลักษณ์พร้อมเส้นเชื่อมการเรียกใช้แบบทั่วไป ซึ่งหมายความว่าเส้นเชื่อมอาจเป็นการจับคู่ชื่อแทนที่จะเป็นการอ้างอิงที่ผ่านการแก้ไขแล้ว เส้นเชื่อมระดับคอมไพเลอร์สามารถเลือกเปิดใช้งานได้ด้วย --lsp และ language server เช่น rust-analyzer หรือ gopls

ติดตั้ง Graft และตรึงเวอร์ชัน

Graft ต้องใช้ Node.js 20 หรือใหม่กว่า และเผยแพร่ภายใต้สัญญาอนุญาต MIT ณ วันที่ 17 October 2026 release ปัจจุบันคือ 0.23.0 ซึ่งเผยแพร่เมื่อ 15 October 2026 ส่วนเวอร์ชันแรกที่เผยแพร่คือ 0.1.0 ลงวันที่ July 2026 ให้ถือว่าเป็นซอฟต์แวร์ที่ยังใหม่อยู่ Release 0.22.0 ซึ่งเผยแพร่เมื่อ 14 October 2026 เปลี่ยนชื่อโครงการเป็น Trail-code โดยโค้ดชุดเดียวกันนี้ยังเผยแพร่ในชื่อ @trailhq/trail-code พร้อมคำสั่ง trail ขณะที่ @nanonets/graft ยังคงใช้คำสั่ง graft

คู่มือนี้ตรึงไว้ที่ 0.21.1 ซึ่งเผยแพร่เมื่อ 29 September 2026 และเป็น release สุดท้ายก่อนการเปลี่ยนชื่อ เนื่องจาก 0.22 และ 0.23 เปลี่ยนคำสั่งที่คู่มือนี้ใช้งาน ตั้งแต่ 0.22 เป็นต้นมา graft check จะเปรียบเทียบ diff ของ branch กับองค์ความรู้ของทีมใน repo และจบการทำงานด้วยค่า 1 หากพบความขัดแย้ง ส่วนการตรวจจับความคลาดเคลื่อนย้ายไปอยู่ที่ graft build --check และเครื่องมือ MCP ใช้ชื่อ trail_* (แต่ server ยังคงตอบสนองชื่อ graft_* เดิม) changelog ของ 0.23.0 ยังระบุว่าใน repo ที่ตั้งค่าด้วย trail map จะย้ายไปที่ .trail/cache/ และ Claude Code จะไม่ได้รับ MCP server อีกต่อไป ขณะที่ README ยังคงอธิบาย graft/ และ .mcp.json โปรดอ่าน changelog และเรียกใช้ --dry-run ก่อนเปลี่ยนเวอร์ชันที่ตรึงไว้

npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graft

npm ls -g ควรแสดง @nanonets/graft@0.21.1 ให้ตรึงเวอร์ชันนี้โดยตั้งใจ การใช้ npm install -g @nanonets/graft แบบไม่ระบุเวอร์ชันจะ resolve ไปยัง tag latest ณ เวลาที่เรียกใช้ และในโครงการที่มีการออก minor release หลายรายการต่อเดือน คุณอาจได้เครื่องมือคนละเวอร์ชันในวันอังคารกับที่เพื่อนร่วมงานติดตั้งไว้ในวันจันทร์ เวอร์ชันที่ตรึงไว้ทำให้ CLI flags และรูปแบบกราฟเหมือนกันสำหรับทุกคน คุณจึงอัปเกรดได้เมื่อเป็นผู้ตัดสินใจเอง

จากนั้นเชื่อมต่อเข้ากับ repository ที่คุณเป็นเจ้าของ:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init จะถามว่าต้องการเชื่อมต่อ coding agent ใดบ้าง แล้วจึงสร้างกราฟ ให้เรียกใช้ --dry-run ก่อน และอ่านรายการไฟล์ที่คำสั่งวางแผนจะแก้ไข เนื่องจากบางไฟล์อยู่นอก repository graft init เป็น idempotent และจะไม่เขียนทับ config ที่มีอยู่ ดังนั้นการเรียกใช้ซ้ำจึงปลอดภัย หากต้องการย้อนกลับ graft uninstall จะลบไฟล์และ config entry ทุกรายการที่ Graft เขียนไว้ โดยคำสั่งจะเป็น dry run จนกว่าจะส่ง -y

prompt เดียวกันนี้มี checkbox สำหรับ telemetry ตั้งแต่ release 0.12.0 Graft จะส่ง ping การใช้งานแบบไม่ระบุตัวตนเป็นค่าเริ่มต้น โดยส่งเฉพาะจำนวนแบบจัดกลุ่มและ label ที่กำหนดตายตัว ไม่ส่งโค้ด, file paths หรือชื่อ repository ของคุณ เหตุการณ์จะถูกส่งไม่เกินวันละ 1 ครั้ง โดยมีข้อยกเว้นคือเหตุการณ์ติดตั้ง ซึ่ง npm's postinstall hook จะส่งให้ background sender ทันที ยกเลิกการเลือกช่องระหว่าง graft init เรียกใช้ graft telemetry disable หรือตั้งค่า DO_NOT_TRACK=1 เพื่อปิดใช้งาน (ระบบจะปิดเองใน CI ด้วย) และ graft telemetry debug จะแสดง batch ที่จะส่งโดยไม่ส่งจริง

ใน 0.21.1 การเชื่อมต่อรองรับ Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent และ Google Antigravity Hermes Agent เป็น graft init host แบบ first-class ตั้งแต่ release 0.13.0 และในเวอร์ชันที่ตรึงไว้ graft init --agents hermes กับ graft init --agents antigravity ใช้เลือก host ทั้งสองรายการได้เช่นเดียวกับ host อื่น Grok เพิ่มเข้ามาใน release 0.13.0 และเลือกได้ด้วย graft init --agents grok Claude Code ได้รับการเชื่อมต่อในระดับลึกที่สุด ได้แก่ MCP server entry, statusline ที่แสดงขนาดกราฟและความล้าสมัย, post-edit hooks ที่สร้างกราฟใหม่ และ skill file ใต้ .claude/ ส่วนรายการอื่นจะได้รับ instruction หรือ rule file ที่แจ้ง agent ว่ามีเครื่องมือเหล่านี้อยู่ (Hermes Agent และ Antigravity อ่าน section AGENTS.md ทั้งคู่) และ Grok ยังได้รับ MCP block ใน config ของตนเองด้วย ดังนั้นคำว่า "รองรับ" จึงหมายความว่า Graft เขียนการเชื่อมต่อให้ หาก agent ข้าม rule file ของตนเอง ก็จะข้าม map ไปด้วย นั่นคือเหตุผลทั่วไปที่ agent ไม่ทำตามคำสั่งที่คุณเขียนไว้ให้ และกรณีนี้ก็ไม่ต่างจากกรณีอื่น

สิ่งที่ถูกเพิ่มลงใน repository ของคุณ และสิ่งที่ควรละเว้นจาก git

หลังจาก graft init ให้คาดหวังผลลัพธ์ดังนี้:

  • graft/: กราฟโหนด markdown และ graft/.graph/wiring.json ซึ่งถูกเพิ่มลงใน .gitignore ให้คุณโดยอัตโนมัติ
  • .mcp.json: ลงทะเบียน graft MCP server เพื่อให้ Claude Code เริ่มการทำงาน
  • .claude/settings.json: ถูกรวมเข้าที่เดิม โดยเพิ่ม statusline และ post-edit hooks
  • AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md, .grok/skills/graft/SKILL.md และ .adal/skills/graft/SKILL.md: ส่วนที่ถูกครอบด้วย marker ซึ่งจะถูกผนวกเข้ากับไฟล์ที่ตรงกับ agent ที่คุณเลือก
  • .grok/config.toml: บล็อก [mcp_servers.graft] ระดับ repository ซึ่งจะถูกเขียนขึ้นเมื่อคุณเลือก Grok เท่านั้น
  • ~/.codex/config.toml, ~/.codex/hooks.json และ ~/.codex/hooks/graft/graft-hooks.cjs: การตั้งค่าระดับเครื่อง ซึ่งจะถูกเขียนขึ้นเมื่อคุณเลือก Codex และ ~/.codex/ มีอยู่แล้วเท่านั้น graft init --no-global จะข้ามการตั้งค่าเหล่านี้ และ graft init --no-hooks จะข้าม hook shim โดยลำพัง

กราฟนี้เป็นแคชเช่นเดียวกับ node_modules ห้าม commit ไฟล์นี้ลงไป มันสามารถสร้างใหม่จากโค้ดได้ในเวลาไม่กี่วินาที มันเปลี่ยนแปลงเกือบทุกครั้งที่มีการแก้ไข และการ commit ไฟล์นี้จะทำให้การแก้ไขเพียงบรรทัดเดียวกลายเป็น diff หลายร้อยไฟล์ที่ไม่มีใครอยากอ่าน ให้ commit เฉพาะส่วนการเชื่อมต่อแทน ซึ่งรวมถึง AGENTS.md และ .mcp.json เพื่อนร่วมทีมของคุณจะ clone repository, รัน graft build และสร้างกราฟในเครื่องของตนเองได้

ตรวจสอบว่ากฎการละเว้น (ignore rule) ถูกเพิ่มเรียบร้อยแล้วก่อนการ commit ครั้งแรกของคุณ:

grep -n graft .gitignore
git status --short

grep ควรแสดงบรรทัดที่มี graft/ และ git status --short ไม่ควรแสดงรายการใดๆ ภายใต้ graft/ หากมีไฟล์ภายใต้ graft/ ปรากฏในผลลัพธ์ดังกล่าว แสดงว่ารายการ ignore ขาดหายไปหรือถูก override ที่อื่น ให้แก้ไขก่อนทำการ commit เพราะ git จะติดตามไฟล์นั้นต่อไปหากเคยถูกเพิ่มเข้าไปแล้ว และการแก้ไข .gitignore ในภายหลังจะไม่ทำให้ไฟล์นั้นหลุดจากการติดตาม

หากคุณต้องการลงทะเบียน MCP server ด้วยตนเอง หรือต้องการล็อกเวอร์ชันให้ตรงกับที่คุณติดตั้งไว้ รายการตั้งค่าจะมีขนาดเล็กดังนี้:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
    }
  }
}

เครื่องมือ retrieval ที่ agent เรียกใช้แทน grep

Graft เปิดให้ใช้เครื่องมือ 6 รายการผ่าน MCP graft_find_code แสดง nodes ที่จัดอันดับตามคำอธิบายงาน พร้อม file และ line graft_file_api แสดง signature ทั้งหมดใน file โดยไม่แสดง body graft_trace_calls ไล่ดู callers หรือ callees ได้ลึกหลายระดับ graft_find_all แสดงผล regex ที่พบโดยจัดกลุ่มตาม symbol graft_repo_map ให้ภาพรวมเบื้องต้นของ repository ที่ยังไม่คุ้นเคย graft_check_freshness รายงานว่า graph ยังคงตรงกับ code หรือไม่

เครื่องมือทุกตัวมี CLI ที่ทำงานเทียบเท่ากัน ซึ่งใช้ตรวจสอบได้ว่า agent ได้รับข้อมูลอะไรจริง:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask ควรแสดง nodes ที่จัดอันดับพร้อม references ของ file:line แทนที่จะแสดงเนื้อหาใน file นี่คือกลไกทั้งหมด: agent ได้รับ pointer แล้วเปิด file เพียง 1 รายการ แทนการอ่าน 10 รายการเพื่อหา file ที่ถูกต้อง graft viz เปิด viewer แบบ interactive บน localhost หากต้องการดู graph ด้วยตนเอง หาก graft ask ไม่คืนผลลัพธ์ที่เป็นประโยชน์สำหรับคำถามที่คุณตอบได้ภายใน 30 วินาที อย่าเปลี่ยนถ้อยคำของคำถามแล้วเรียกใช้อีกครั้ง Ranked retrieval อาจพลาดได้ และ skill file ของ project ระบุว่าเมื่อผลลัพธ์อ่อน ควรเปลี่ยนไปใช้ graft grep, graft skeleton หรือ graft callers หากเครื่องมือเหล่านี้ยังให้ผลไม่เพียงพอ ให้ตรวจสอบว่าเกิด drift หรือไม่ (graft check . บน pinned 0.21.1 และ graft build --check ตั้งแต่ 0.22 เป็นต้นไป) และยืนยันว่า language ของคุณอยู่ใน tier ใด เพราะ graph ที่ล้าสมัยหรือ edges จาก broad tier จะทำให้ agent ทำงานล้มเหลวในลักษณะเดียวกัน

มีต้นทุนอย่างหนึ่งที่มองข้ามได้ง่าย คำจำกัดความของเครื่องมือทั้ง 6 รายการจะถูก inject เข้าไปใน system prompt ของทุก request ตลอดทั้ง session คุณต้องจ่ายต้นทุนนี้ไม่ว่า agent จะใช้ map หรือไม่ก็ตาม สำหรับ repository ที่มีขนาดเล็กพอจะใส่ไว้ใน context ได้ ต้นทุนคงที่นี้อาจสูงกว่าการสำรวจที่ช่วยลดได้.

จะเกิดอะไรขึ้นกับกราฟเมื่อโค้ดเปลี่ยนแปลง

การรีเฟรชโครงสร้างใช้ทรัพยากรน้อยและทำงานโดยอัตโนมัติ Graft อ่าน working tree แทน git ดังนั้นทั้งการแก้ไขที่ยังไม่ได้ commit และการแก้ไขที่ stage แล้วจึงมองเห็นได้เท่าเทียมกัน ทุก query จะตรวจสอบ working tree ก่อน แล้ว parse ใหม่เฉพาะไฟล์ที่เปลี่ยนแปลงเท่านั้น เอกสารของ 0.21.1 ระบุว่าการตรวจสอบนี้ใช้เวลาประมาณ 3 ms เมื่อไม่มีสิ่งใดเปลี่ยนแปลง ส่วน README ปัจจุบันระบุว่าใช้เวลาไม่กี่สิบมิลลิวินาที หรือประมาณ 50 ms เมื่อทำงานกับ repository ของโครงการเอง การ rebuild ตอนจบของแต่ละ turn จะประมวลผลเฉพาะไฟล์ที่มีการย้ายโค้ดเท่านั้น กำหนด GRAFT_NO_REFRESH=1 หรือส่ง --no-refresh เพื่อให้ตอบจากกราฟที่อยู่บนดิสก์โดยไม่ parse ใหม่ ส่ง --no-reuse เพื่อบังคับให้ parse ใหม่ทั้งหมดตั้งแต่ต้น ซึ่งเป็นสิ่งที่ควรทำหลังอัปเกรด Graft เอง

ส่วนที่ model เขียนมีพฤติกรรมต่างออกไป และเป็นส่วนที่มักผิดพลาดโดยไม่แสดงอาการ สรุปและ crux จะถูก cache ไว้ แต่ละ node จะบันทึก content hash ของ source ดังนั้นเมื่อไฟล์ต้นทางเปลี่ยนแปลง node จะถูกทำเครื่องหมายว่า stale แทนที่จะนำเสนอว่าเป็นข้อมูลปัจจุบัน การทำเครื่องหมายนี้จะมีประโยชน์ก็ต่อเมื่อมีสิ่งใดดำเนินการกับมัน ให้รีเฟรชด้วย graft build --deep ซึ่งจะใช้ model tokens อีกครั้ง

ทำให้สถานะ stale มองเห็นได้:

graft check .
echo $?

สำหรับ 0.21.1 ที่ pin ไว้ exit status 0 หมายความว่ากราฟตรงกับโค้ด และ exit status 1 หมายความว่าเกิด drift ตั้งแต่ 0.22 เป็นต้นไป graft check จะคืนค่า exit status 1 เมื่อเกิด conflict กับ team learning แทน ส่วนคำสั่งสำหรับตรวจ drift คือ graft build --check ดังนั้นให้เปลี่ยน command เมื่อเปลี่ยน pin เรียกใช้จาก pre-push hook เพื่อไม่ให้ map ที่มีอายุ 6 เดือนตอบอย่างมั่นใจเกี่ยวกับโค้ดที่ถูกเขียนใหม่ในเดือนมีนาคม README ของ 0.21.1 อธิบาย graft check ว่าเป็นสัญญาณ freshness ภายในเครื่อง และ README ปัจจุบันระบุ build --check สำหรับ CI ไม่ว่ากรณีใด graft/ จะถูก git-ignored ดังนั้น fresh CI checkout จะเริ่มต้นโดยไม่มีกราฟ เว้นแต่งานนั้นจะสร้างกราฟขึ้นมาเอง

อ่านตัวเลข benchmark ที่เผยแพร่อย่างละเอียด

README ของ 0.21.1 เริ่มต้นด้วยข้อความว่า “ถูกลงสูงสุด 4x และเร็วขึ้น 3x โดยความถูกต้องดีขึ้นหรือไม่ลดลง” แต่ README ปัจจุบันตัดข้อความดังกล่าวออก และเริ่มด้วยตัวเลขที่น้อยกว่า: “จากการรัน agent เดิมบนงานเดิม 162 ครั้ง: ค่าใช้จ่ายลดลง 32%, uncached input tokens ลดลง 42%, ใช้เวลาน้อยลง 60% และมีสัดส่วนคำตอบที่ถูกต้องเท่าเดิม” ตัวเลขเหล่านี้มาจาก benchmark ของโครงการเอง ซึ่งเผยแพร่ไว้ใน README ต่อไปนี้คือการรัน 2 ชุดที่โครงการรายงานโดยละเอียด

แผนภูมิGraft's own published benchmark results, versus a no-map baseline, as of October 2026
ข้อมูลเบื้องหลังแผนภูมินี้
[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

การทดสอบแบบควบคุมประกอบด้วยการรัน 162 ครั้งบน repository 2 แห่ง โดยหนึ่งแห่งคือ Graft เอง และทดลองแต่ละงาน 3 ครั้ง รายงานว่า uncached input tokens ลดลง 42% และ tool calls ลดลง 46% ส่วนการรัน SWE-bench Verified มี 50 instances โดยใช้ model เดียวกันทั้ง 2 ฝั่ง และรายงานการลดลงที่น้อยกว่า: tokens ลดลง 23% และ tool calls ลดลง 25% การรันชุดที่ 3 กับงาน PocketBase 15 งาน ซึ่งประกอบด้วยคำถามจากนักพัฒนา 10 ข้อและ pull requests ที่ merge แล้วซึ่งนำมาทำซ้ำ 5 รายการ มีค่าใช้จ่ายรวม 11.02 US dollars เทียบกับ 13.91 สำหรับ baseline

ให้ถือว่าข้อมูลทั้งหมดเป็น vendor benchmark ข้อมูลนี้มีข้อจำกัด 2 ประการ การทดสอบแบบควบคุมรวม repository ของ Graft เอง ซึ่งเป็น codebase ที่ผู้เขียนใช้ปรับแต่งเครื่องมือ SWE-bench Verified เป็นชุดข้อมูลสาธารณะของ issues จากโครงการ Python แบบ open-source ที่เป็นที่รู้จัก และชุดข้อมูลสาธารณะเป็นชุดข้อมูลที่เครื่องมือต่าง ๆ มักได้รับการ optimize ให้รองรับ ไม่ว่าใครจะตั้งใจเช่นนั้นหรือไม่ก็ตาม ข้อมูลทั้ง 2 ชุดไม่ได้บอกผลลัพธ์สำหรับ private monorepo ของคุณ ซึ่งมีรูปแบบการตั้งชื่อและ dead code เป็นของตนเอง

ควรอ่านผลด้านความถูกต้องซ้ำอีกครั้ง ในการทดสอบแบบควบคุม ผลดังกล่าวไม่เปลี่ยนแปลง: 93% เมื่อใช้ map เทียบกับ 93% เมื่อไม่ใช้ การเพิ่มขึ้นเป็น 66% จาก 54% ปรากฏเฉพาะบน SWE-bench Verified เท่านั้น เครื่องมือที่ลดค่าใช้จ่ายด้าน tokens ของคุณโดยที่คุณภาพไม่เปลี่ยนแปลงยังถือว่าเป็น trade-off ที่ดี แต่อย่านำผลด้านความถูกต้องจาก SWE-bench ไปใช้กับผลด้าน tokens จากการทดสอบแบบควบคุม แล้วอ้างทั้ง 2 อย่างเป็นข้อสรุปเดียวกัน

วัดค่าส่วนต่างของโทเค็นด้วยตัวเองก่อนจะเชื่อข้อมูลใดๆ

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

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

เปิดใช้งาน telemetry และส่งข้อมูลไปยัง terminal ของคุณ:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

Console exporter จะพิมพ์บันทึก metric ออกมาในขณะที่ข้อมูลถูกรวบรวม สิ่งที่คุณต้องการคือ claude_code.token.usage ซึ่งมี attribute type เป็น input, output, cacheRead หรือ cacheCreation ข้อมูลทิศทางจะปรากฏใน input และ cacheRead เนื่องจากเป็นจุดที่เนื้อหาไฟล์ถูกจัดเก็บ ให้นำค่าทั้งสองมารวมกัน

รันงานดังกล่าว 3 ครั้ง โดยแต่ละครั้งต้องอยู่ใน session ใหม่ที่เชื่อมต่อ map ไว้ จากนั้นให้นำรายการ graft ออกจาก .mcp.json แล้วรันซ้ำอีก 3 ครั้ง ให้เปรียบเทียบค่ามัธยฐานแทนการดูผลลัพธ์จากการรันเพียงครั้งเดียว เนื่องจากการรันของ agent มีความผันผวนสูง และการรันที่โชคร้ายเพียงครั้งเดียวอาจให้ผลลัพธ์ที่ตรงกันข้ามกับความเป็นจริง นอกจากนี้ให้บันทึกจำนวนการเรียกใช้เครื่องมือ (tool-call) ไว้ด้วย เพราะการเรียกใช้เครื่องมือคือกลไก และโทเค็นคือผลลัพธ์ ดังนั้นหากโทเค็นลดลงโดยที่จำนวนการเรียกใช้เครื่องมือไม่ลดลง แสดงว่ามีปัจจัยอื่นที่เปลี่ยนแปลงไป

จากนั้นให้หักลบค่าใช้จ่ายที่ benchmark ไม่ได้แสดงให้เห็น graft build --deep ใช้โทเค็นของโมเดลในการ refresh ข้อมูลทั้งหมดทุกครั้ง โดย schema ของเครื่องมือทั้ง 6 รายการจะถูกส่งไปพร้อมกับทุกคำขอ หาก agent ของคุณรันบนเซิร์ฟเวอร์ที่คุณเช่า การกำหนดเพดานค่าใช้จ่ายสูงสุดสำหรับ agent จะช่วยเปลี่ยนจากเหตุการณ์ไม่คาดคิดให้กลายเป็นงบประมาณที่ควบคุมได้ และ สิ่งที่ telemetry ของ coding agent รายงานจริง จะครอบคลุมถึงข้อมูลที่ถูกส่งออกจากเครื่องเมื่อคุณเปิดใช้งาน exporter แล้ว

จุดใดที่แผนผัง codebase ไม่ได้ช่วยอีกต่อไป

  • Repository มีขนาดพอดีกับ context อยู่แล้ว บริการขนาดเล็กเพียงตัวเดียวไม่จำเป็นต้องมีแผนผัง และคุณยังต้องเสียค่าใช้จ่ายกับ schema ของเครื่องมือ 6 รายการในทุกคำขอ หาก agent ค้นหาไฟล์ใดๆ ได้ในวันนี้ด้วยการเรียกใช้เครื่องมือ 1 หรือ 2 ครั้ง ให้ข้ามแผนผังไป
  • ภาษาอยู่ในกลุ่ม broad tier ขอบการเรียกใช้แบบทั่วไปอาจทำให้ graft callers พลาด caller หรือสร้าง caller จากชื่อที่ซ้ำกันได้ ให้ยืนยันด้วย graft grep ก่อนเชื่อถือ blast radius
  • กราฟล้าสมัยและไม่มีใครสังเกตเห็น ใน 0.21.1 graft check จะจบการทำงานด้วยสถานะ 1 เมื่อพบ drift (ตั้งแต่ 0.22 เป็นต้นไป graft build --check จะทำเช่นนั้น) ซึ่งจะมีประโยชน์ก็ต่อเมื่อมีสิ่งใดเรียกใช้ ให้ใช้ pre-push hook ไม่ใช่อาศัยความเคยชิน
  • monorepo ต้องกำหนดขอบเขต monorepo ที่ใช้ git เพียงชุดเดียวจะไม่ถูกแยกออกเป็นส่วนๆ แต่ graft build ตรวจจับ sub-projects จาก pnpm-workspace.yaml, package.json workspaces หรือ go.mod, pyproject.toml หรือ Cargo.toml ระดับ package ได้ และใช้สิ่งเหล่านี้เป็นขอบเขตสำหรับจัดอันดับ ส่วน graft ask "..." --in services/billing/ จะจำกัด query ให้เหลือ sub-project เดียว แนวคิดเดียวกับที่นำไปสู่การใช้ ไฟล์ AGENTS.md แบบซ้อนกันในแต่ละ package ควรนำมาใช้กับแผนผังนี้ด้วย
  • agent ไม่สนใจการเชื่อมต่อการทำงาน ตรวจสอบการเรียกใช้เครื่องมือในเซสชันจริงก่อนสรุปว่ามีการใช้แผนผัง หาก agent ยังคงเรียกใช้ grep นั่นแสดงว่าไม่เคยอ่านไฟล์ rulesเลย

FAQ

ควร commit โฟลเดอร์ graft/ ลงใน git หรือไม่

ไม่ควร graft build จะเพิ่ม graft/ ลงใน .gitignore ของคุณโดยอัตโนมัติ เพราะ graph เป็น cache ที่สร้างใหม่ได้ เช่นเดียวกับ node_modules graph จะเปลี่ยนแปลงในการแก้ไขเกือบทุกครั้ง การ commit graph จึงทำให้ diff จริงถูกกลบด้วยไฟล์ที่สร้างขึ้นหลายร้อยไฟล์ ให้ commit เฉพาะการเชื่อมต่อที่บอก agent ว่ามี map อยู่ ซึ่งรวมถึง AGENTS.md และ .mcp.json แล้วให้สมาชิกแต่ละคนเรียกใช้ graft build ในเครื่องของตน ตรวจสอบด้วย grep -n graft .gitignore และ git status --short ก่อน commit ครั้งแรก เพราะ git จะติดตามไฟล์ต่อไปเมื่อไฟล์นั้นถูกเพิ่มแล้ว และการแก้ไข .gitignore ในภายหลังจะไม่ยกเลิกการติดตามไฟล์นั้น

Graft มีค่าใช้จ่ายในการเรียกใช้หรือไม่

ส่วนที่สร้างโครงสร้างไม่มีค่าใช้จ่าย graft build, graft ask, graft check และเครื่องมือ MCP สำหรับ retrieval ทั้ง 6 รายการเป็นการทำงานของ tree-sitter ที่ไม่เรียกใช้ model ส่วนที่มีค่าใช้จ่ายคือ graft build --deep ซึ่งเขียนสรุปภาษาอังกฤษแบบอ่านง่ายและ crux ของแต่ละ symbol ผ่าน LLM โดยกำหนดค่าด้วย GRAFT_PROVIDER, GRAFT_API_KEY และ GRAFT_MODEL รวมถึง GRAFT_BASE_URL สำหรับ endpoint ที่เข้ากันได้กับ OpenAI คุณสามารถเรียกใช้ Graft โดยมีเฉพาะโครงสร้าง และไม่ใช้ token กับ graph เองเลย

map ของ codebase จะช่วยประหยัดค่าใช้จ่ายใน repository ของฉันได้มากเพียงใด

ไม่มีใครบอกได้หากไม่ทำการวัด โครงการรายงานว่าใช้ input token ที่ไม่ได้อยู่ใน cache น้อยลง 42% จากการทดสอบ 162 รอบของโครงการเอง และใช้ token น้อยลง 23% บน SWE-bench Verified โดยทั้งสองตัวเลขเปรียบเทียบกับ baseline ที่ไม่มี map ตัวเลขทั้งสองเป็น benchmark ของผู้พัฒนา โดยหนึ่งการทดสอบใช้ repository ของ Graft เองบางส่วน และไม่มีตัวเลขใดอธิบายผลกับ code ส่วนตัวของคุณได้ ให้เรียกใช้คำถามเดิมที่ทำซ้ำได้ 3 ครั้งโดยมี map และ 3 ครั้งโดยไม่มี map โดยกำหนด CLAUDE_CODE_ENABLE_TELEMETRY=1 และ OTEL_METRICS_EXPORTER=console แล้วเปรียบเทียบค่ามัธยฐานของ claude_code.token.usage สำหรับประเภท input และ cacheRead

graph จะเป็นอย่างไรเมื่อ refactor

ส่วนโครงสร้างจะ parse ใหม่ด้วยตัวเอง Graft จะตรวจสถานะของ working tree และ parse ใหม่เฉพาะไฟล์ที่เปลี่ยนแปลง ดังนั้น rename จะถูกตรวจพบในการ query ครั้งถัดไป เมื่อไม่มีสิ่งใดย้าย การตรวจสอบนี้ใช้เวลาประมาณ 3 ms ใน 0.21.1 และไม่กี่สิบมิลลิวินาทีใน release ปัจจุบัน การตรวจสอบยังเห็นงานที่ยังไม่ได้ commit เพราะอ่านไฟล์โดยตรง ไม่ได้อ่านประวัติ git ส่วนที่ล้าสมัยคือสรุปที่ model เขียน แต่ละ node จะเก็บ content hash ของ source ไว้ และเมื่อ source เปลี่ยน ระบบจะทำเครื่องหมาย node ว่าล้าสมัยแทนการเขียนทับ ตรวจสอบ drift ด้วย (graft check . ใน 0.21.1, graft build --check ตั้งแต่ 0.22 เป็นต้นไป) จากนั้นเรียกใช้ graft build --deep เพื่อปรับปรุงส่วนที่เขียนไว้

ปัจจุบัน coding agent ใดใช้ Graft ได้บ้าง

ใน 0.21.1 ที่ตรึงเวอร์ชันไว้ graft init จะเชื่อมต่อ Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent และ Google Antigravity รวมทั้งหมด 11 host changelog ระบุ Hermes Agent เป็น host ระดับ first-class ตั้งแต่ 0.13.0 และ hermes กับ antigravity เป็น id ของ --agents ตามปกติใน release ที่ตรึงเวอร์ชันไว้ Claude Code ได้รับการรองรับมากที่สุด ได้แก่รายการ MCP server ใน .mcp.json, statusline, post-edit hooks และไฟล์ skill ใน .claude/ Codex ได้รับ section AGENTS.md รวมถึงรายการระดับทั้งเครื่องใน ~/.codex/ ซึ่ง graft init --no-global จะไม่ดำเนินการ Grok ได้รับไฟล์ skill พร้อม MCP block ใน .grok/config.toml Hermes Agent และ Antigravity อ่าน section AGENTS.md ส่วน host อื่นจะได้รับไฟล์ rules หรือ steering ลูกค้า MCP อื่นใดสามารถใช้ server ได้โดยตรงด้วยการลงทะเบียนคำสั่ง npx -y @nanonets/graft@0.21.1 mcp

บทความนี้มีประโยชน์หรือไม่