Claude Code Merge Queue เป็นเครื่องมือฟรีที่มีหน้าที่หลักคือปฏิเสธคำสั่ง push ของเราเอง พอ agent ที่ช่วยเขียนโค้ดทำงานเสร็จ แล้วสั่ง git push ตรงเข้า branch กลางของโปรเจกต์ มันจะเด้งกลับทันที แถมบอกด้วยว่าคำสั่งที่ต้องใช้แทนคืออะไร คนทำคือ funador ปล่อยโค้ดไว้บน GitHub ด้วยใบอนุญาต MIT ตอนที่เขียนบทความนี้ ตัวโปรเจกต์อยู่ที่เวอร์ชัน v0.5.8 และมีดาว 101 ดวง

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

ปัญหาไม่ได้อยู่ตอน agent เขียนโค้ด

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

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

เรื่องนี้ไม่ใช่ความกังวลที่คิดกันไปเอง เอกสารทางการของ Claude Code เขียนเตือนไว้เองว่าถ้าปล่อยให้เพื่อนร่วมทีมสองตัวลงมือแก้ไฟล์เดียวกัน งานจะเขียนทับกันจนของหายไปเลย ทางที่เอกสารบอกให้ทำคือแบ่งงานให้แต่ละตัวถือไฟล์คนละชุด ส่วนคนที่อยากรันหลาย session (หน้าต่างทำงาน) พร้อมกันเอง เอกสารชุดเดียวกันก็ชี้ไปที่การแยกโฟลเดอร์ทำงานของแต่ละ session ออกจากกันด้วย git worktree และนั่นคือฐานที่ Claude Code Merge Queue ต่อยอดขึ้นไปพอดี ฝั่ง Claude Code เองก็เพิ่ม Agent View มาให้ดูแล session ที่รันพร้อมกันหลายตัวจากหน้าจอเดียว แต่ตัวนั้นช่วยเรื่องการมองเห็น ไม่ได้จัดลำดับให้ตอนโค้ดมารวมกัน

lane หนึ่งตัว ได้ worktree กับพอร์ตของตัวเอง

หน่วยการทำงานของเครื่องมือนี้เรียกว่า lane งานแต่ละชิ้นได้ branch ของตัวเองที่ขึ้นต้นด้วยคำที่ตั้งไว้ในฟิลด์ branchPrefix ค่าในตัวอย่าง config คือ lane/ แล้วไล่เป็น lane/1, lane/2 ต่อกันไป

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

พอไฟล์แยกกันแล้ว ของที่ต้องแยกตามคือพอร์ตของ dev server ที่เอาไว้เปิดดูงานในเบราว์เซอร์ แต่ละ lane ได้เลขพอร์ตของตัวเองที่คำนวณจากฟิลด์ portBase ตัวอย่างใน config ตั้งไว้ที่ 3000 lane ที่ n ก็ได้พอร์ต 3000 + n ไล่กันไปทีละเลข และไม่ต้องมานั่งจำว่าหน้าต่างไหนเปิดพอร์ตอะไร เพราะสั่ง claude-code-merge-queue port ในโฟลเดอร์นั้น แล้วมันพิมพ์เลขพอร์ตของ lane นั้นออกมาให้เลย

land คือประตูเดียวที่โค้ดผ่านเข้าไปได้

เมื่อ agent ทำงานเสร็จ มันจะไม่ push เอง แต่เรียกคำสั่ง claude-code-merge-queue land แทน คำสั่งนี้จะ rebase งานของ lane ตัวเอง คือย้ายไปต่อบนโค้ดล่าสุดที่เพิ่งลงไป แล้วค่อย push เข้า branch กลาง โดยเข้าคิวแบบมาก่อนได้ก่อน ทีละหนึ่งตัวเท่านั้น สอง lane บนเครื่องเดียวกันจึงไม่มีทางอยู่ระหว่าง push พร้อมกัน ไม่ใช่เพราะเราคอยดูจังหวะให้ แต่เพราะตัวที่มาทีหลังจะรออยู่ในคิวจนตัวแรกเสร็จ และ agent เป็นคนเรียกคำสั่งนี้เอง ไม่ต้องรอใครสั่ง

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

ส่วน build ที่กินเครื่องหนักๆ มีคำสั่งของมันแยกอีกตัวคือ claude-code-merge-queue build-lock -- <cmd> ซึ่งรับคำสั่ง build ของเราไปรัน แล้วบังคับให้รันได้ทีละอันทั้งเครื่อง ไม่ว่าคำสั่งนั้นจะสั่งมาจาก lane ไหนก็ตาม

pre-push hook ปิดทางลัดข้ามคิว

ถ้ามีแค่คำสั่ง land วางไว้เฉยๆ มันก็เป็นแค่คำแนะนำที่ agent จะทำตามหรือไม่ทำก็ได้ ตอน init เครื่องมือนี้เลยติดตั้ง pre-push hook เอาไว้ด้วย ซึ่งเป็นสคริปต์ที่ git เรียกเองทุกครั้งก่อนจะ push จริง ผลคือถ้ามีใครสั่ง push ตรงเข้า branch กลางโดยไม่ผ่านคิว git จะปฏิเสธทันที แล้วขึ้นข้อความบอกคำสั่งที่ถูกต้องให้ไปทำแทน ไม่ใช่ error ปริศนาที่ต้องมานั่งเดาเอง

hook ตัวเดียวกันนี้ยังทำอีกหน้าที่หนึ่ง คือรันคำสั่งที่ตั้งไว้ในฟิลด์ checkCommand ก่อนจะยอมให้โค้ดชุดนั้นลงได้ ในตัวอย่าง config ค่านี้คือ npm run check แปลว่าถ้าเทสต์หรือคำสั่งเช็คโค้ดอย่าง lint ไม่ผ่าน โค้ดก็ไม่มีทางเข้า branch กลาง และถ้าไม่ได้ตั้ง checkCommand เอาไว้เลย ทุก push จะไม่ผ่านตั้งแต่ต้น เป็นการเลือกให้พังไว้ก่อน แทนที่จะปล่อยผ่านแบบเงียบๆ

คำสั่งที่ต้องใช้จริงในแต่ละวัน

ของที่ต้องจำมีไม่กี่ตัว และแบ่งชัดว่าตัวไหนเป็นของ agent ตัวไหนเป็นของคน

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

ติดตั้งสองบรรทัด แล้ว init เขียนไฟล์ที่เหลือให้

การเริ่มใช้ยาวแค่นี้

npm install --save-dev claude-code-merge-queue
npx claude-code-merge-queue init

ใครใช้ pnpm, yarn หรือ bun ก็สลับบรรทัดแรกไปเป็นคำสั่งของตัวจัดการแพ็กเกจนั้นได้ ส่วน init คือตัวที่ลงมือเขียนไฟล์ให้จริง

ไฟล์ที่ init เขียนให้มีดังนี้

• claude-code-merge-queue.config.mjs คือ config ไฟล์เดียวจบ โดยมันเดาค่า integrationBranch กับ checkCommand ให้เองจากโปรเจกต์
• CLAUDE.md สร้างใหม่ให้ หรือถ้ามีอยู่แล้วก็ต่อท้ายของเดิม เนื้อหาคือบอก Claude Code ว่าพองานของตัวเองผ่านเช็คแล้ว ให้เรียก land เองได้เลย ไม่ต้องรอใครสั่ง
• .claude/settings.json ผูก WorktreeCreate hook เข้าไป โดยไม่ไปแตะของเดิมที่ตั้งไว้อยู่แล้ว
• .husky/pre-push สร้างใหม่หรือต่อท้ายให้ ถ้าโปรเจกต์ใช้ Husky ตัวจัดการ hook ของ git อยู่ก่อนแล้ว ส่วนโปรเจกต์ที่ยังไม่มี Husky มันจะบอกให้รู้ตัว แทนที่จะแอบไปเขียนลง .git/hooks/pre-push ซึ่งเป็นไฟล์ที่ git ไม่เก็บประวัติไว้ให้
• script ใน package.json ได้แก่ land, sync, promote, preview, preview:restore โดยข้ามตัวที่เราตั้งชื่อซ้ำไว้เองแล้ว
• claude-code-merge-queue-preflight.mjs เป็นตัวเช็คก่อนจะ land หรือ sync เพื่อให้ branch เก่าที่ยังไม่มีของพวกนี้ล้มเหลวพร้อมคำอธิบายว่าเกิดอะไรขึ้น แทนที่จะขึ้นแค่ command not found

ตัว config รวมทุกฟิลด์ไว้ที่เดียว ตั้งแต่ branchPrefix, portBase, integrationBranch, productionBranch, protectedBranches ไปจนถึง checkCommand ถ้ากรอกอะไรผิดรูปแบบ เช่นชื่อ branch ว่าง พอร์ตติดลบ หรือตั้ง productionBranch ซ้ำกับ integrationBranch มันจะล้มตั้งแต่ตอนโหลด config แล้วไล่บอกทุกจุดที่ผิดในครั้งเดียว ไม่ปล่อยให้ไปเจอ error งงๆ เอาตอนหลัง

GitHub Merge Queue ทำเรื่องเดียวกัน แต่คนละราคา

ไอเดียคิวรวมโค้ดไม่ใช่ของใหม่ GitHub มีของแบบนี้อยู่แล้วในชื่อ Merge Queue แต่เงื่อนไขการเข้าถึงต่างกันชัดเจน

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

ข้อจำกัดที่ README บอกไว้ตรงๆ

ส่วนที่ควรอ่านก่อนตัดสินใจใช้คือหัวข้อ Know the limits ซึ่งเจ้าของโปรเจกต์นั่งเขียนข้อเสียของงานตัวเองเอาไว้

ข้อแรกคือมันใช้ได้กับเครื่องเดียว ไม่ใช่กับทีมที่กระจายกันอยู่หลายเครื่อง เพราะคิวเก็บอยู่ในพื้นที่เก็บข้อมูลชั่วคราว (temp storage) ของเครื่องนั้นล้วนๆ ถ้าสองเครื่องสั่ง land พร้อมกัน สิ่งที่จะเจอก็คือ git เด้ง non-fast-forward กลับมาแบบเดิมๆ เหมือนไม่ได้ติดตั้งอะไรไว้เลย

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

ข้อสามคือมันไม่ได้ทำหน้าที่กั้นเรื่องความปลอดภัย ทุกการบล็อกในระบบนี้มีทางผ่านฉุกเฉินอยู่ ใส่ตัวแปรเดียวหน้าคำสั่งอย่าง CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push origin HEAD:main ก็ไปต่อได้ ไม่มีการถามยืนยันซ้ำ และในเมื่อ agent มีสิทธิ์สั่งงานใน shell อยู่แล้ว มันสั่ง git push --no-verify หรือแก้ config เองก็ยังได้ README เรียกสิ่งนี้ว่าข้อตกลง ไม่ใช่การรับประกัน มันกันเรื่องพลาดมือกับการลืมทำตามที่ตกลงกันไว้ ไม่ได้ออกแบบมากัน agent ที่ตั้งใจจะข้าม

ข้อสุดท้ายคือเวลา rebase ชนกัน มันสั่ง git rebase --abort ให้ทันที คืนโฟลเดอร์งานที่สะอาดกลับมา แล้วหยุดอยู่แค่นั้น ไม่พยายามเดาว่าควรแก้ยังไง คนที่ต้องไปนั่งแก้ conflict คือ agent เจ้าของ lane นั้นเอง โดย CLAUDE.md ที่ init เขียนไว้ให้ ก็สั่ง agent อยู่แล้วว่าให้แก้ conflict แล้วเรียก land ใหม่อีกรอบ

กติกาที่เขียนไว้ในไฟล์

บรรทัดปิดท้าย README บอกให้เอาไป fork ต่อ เปลี่ยนชื่อ แล้วเถียงกับรูปร่างของ config ได้ตามสบาย ซึ่งพอมองย้อนกลับไป ทั้ง lane ทั้งคิว ทั้ง hook ก็คือกติกาชุดหนึ่งที่เขียนลงเป็นไฟล์ ให้ทั้งคนและ agent เปิดอ่านฉบับเดียวกัน จากที่เมื่อก่อนกติกาแบบนี้อยู่ในหัวของคนตั้งโปรเจกต์อยู่คนเดียว ส่วนไฟล์ที่ว่านี้ก็เขียนพลาดได้พอๆ กับที่เขียนถูก

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

ที่มา:

• โปรเจกต์ claude-code-merge-queue · The local merge queue for parallel Claude Code agents บน GitHub
• เอกสารทางการของ Orchestrate teams of Claude Code sessions