วิธีตั้ง next-devtools-mcp ให้ Claude Code ใช้กับ Next.js 16

ในโพสต์เรื่อง Laravel Boost Boost ให้ AI agent สามอย่าง guideline ตามเวอร์ชันของ package ที่ติดตั้งจริง MCP server ที่ agent ถามแอปได้เอง และที่เก็บข้อตกลงของโปรเจกต์ใน .ai/rules

ฝั่ง Next.js ไม่มี Boost แต่ agent ก็ยังต้องรู้เรื่องเดียวกัน คือโปรเจกต์ใช้ Next เวอร์ชันไหน ตอนนี้หน้าไหน error และทีมตกลงอะไรกันไว้ บทนี้เป็นงานแรกก่อนเริ่มเขียนโค้ด ไล่ดูว่า Next 16 มีอะไรให้แล้ว และต้องเติมอะไรเองบ้าง ตัวอย่างมาจากร้านค้าออนไลน์ Next.js 16 กับ CMS ที่เป็น Next.js admin ใน pnpm monorepo เดียวกัน ที่เราดูแลอยู่

Next.js 16 แนบเอกสารตรงเวอร์ชันมากับ package#

ปัญหาที่เจอบ่อยที่สุดเวลาให้ agent เขียน Next.js คือ agent จำ API จากเวอร์ชันเก่า Next เปลี่ยนเร็ว ทั้งเรื่อง cache การตั้งค่า และโครงสร้างไฟล์ สิ่งที่ agent จำมาจากตอน train จึงอาจผิดไปแล้วสองสามเวอร์ชัน

Next.js 16 แก้ด้วยการใส่เอกสารทั้งชุดมากับ package เลย อยู่ที่ node_modules/next/dist/docs/ ใน Next 16.3.0 ที่โปรเจกต์นี้ใช้มี 444 ไฟล์ แบ่งเป็น App Router, Pages Router, architecture และ community เนื้อหาตรงกับเวอร์ชันที่ติดตั้งอยู่เสมอ เพราะอัปเดต Next เมื่อไหร่ เอกสารก็เปลี่ยนตามไปด้วย

ส่วนที่บอก agent ว่าต้องไปอ่านตรงนั้นก็มาจาก Next เหมือนกัน ตั้งแต่ Next 16.3 ตอนรัน next dev ถ้า Next ตรวจเจอว่ากำลังรันอยู่ใต้ AI agent และยังไม่มีบล็อกนี้ ก็จะเขียนให้เอง ลงใน AGENTS.md ถ้ามีไฟล์นี้อยู่แล้ว หรือลงใน CLAUDE.md ถ้ามีแค่ไฟล์นั้น ถ้าไม่มีทั้งคู่ก็สร้าง AGENTS.md กับ CLAUDE.md ที่มีแค่ @AGENTS.md ให้ Claude Code อ่านต่อ

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all
differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/`
before writing any code. Heed deprecation notices.

<!-- END:nextjs-agent-rules -->

หัวข้อบอกตรง ๆ ว่า "นี่ไม่ใช่ Next.js ที่คุณรู้จัก" ให้ agent อ่านเอกสารในเครื่องก่อนเขียนโค้ด แทนที่จะเชื่อความจำ เทียบกับ Boost ก็คือส่วน guideline กับ Search Docs รวมกัน ต่างกันตรงที่ Next ไม่ได้เขียนสรุปเรื่องที่เปลี่ยนให้ แค่ชี้ไปที่เอกสารทั้งชุด

next dev เขียนบล็อกนี้กลับมาทุกครั้งที่หายไป ถ้าเราลบออกจาก diff บล็อกก็กลับมาเป็นไฟล์ที่แก้ค้างอยู่ในรอบถัดไป ทางที่ง่ายที่สุดจึงเป็น commit บล็อกนี้เข้า repo ไปเลย ใน monorepo ที่มีแอป Next สองตัว บล็อกนี้อยู่ใน AGENTS.md หรือ CLAUDE.md ของแต่ละแอป เพราะ next ของแต่ละแอปอาจเป็นคนละเวอร์ชัน และ agent ต้องอ่านเอกสารจาก node_modules ของแอปที่กำลังแก้

dev server ของ Next.js 16 มี MCP อยู่แล้ว#

MCP (Model Context Protocol) คือมาตรฐานที่ให้ agent เรียกเครื่องมือภายนอกได้ ใน Laravel Boost เป็นคำสั่ง php artisan boost:mcp ส่วน Next.js 16 ใส่ MCP ไว้ใน dev server เลย ทุกครั้งที่รัน next dev จะมี endpoint ที่ /_next/mcp เปิดอยู่ (ตั้งค่าไว้ที่ experimental.mcpServer ค่าเริ่มต้นเป็น true) เครื่องมือที่ได้มีดังนี้

ข้อที่ใช้บ่อยคือ get-errors เวลาหน้าเว็บพัง agent ดู error เองได้ ไม่ต้องให้เรา copy จากเบราว์เซอร์มาวาง ส่วน get-server-action-by-id ช่วยตอนเจอ error ที่ขึ้นแค่ ID ยาว ๆ ของ server action โดยไม่บอกว่าเป็นฟังก์ชันไหน

endpoint นี้มีเฉพาะตอนที่ dev server รันอยู่ ในโปรเจกต์นี้เราตั้งกฎไว้ว่า agent ไม่สั่งเปิด dev server เอง ให้ใช้ตัวที่นักพัฒนาเปิดไว้ agent จึงใช้ MCP ได้เมื่อเราเปิดเว็บไว้ทำงานอยู่แล้ว ซึ่งก็เป็นจังหวะที่ต้องใช้พอดี

next-devtools-mcp เชื่อม Claude Code เข้ากับ dev server#

endpoint ของ Next อยู่ในแต่ละ dev server และแต่ละตัวอาจรันคนละ port Vercel จึงทำ next-devtools-mcp มาเป็นตัวกลาง ลงทะเบียนไว้ใน .mcp.json ที่ root ของ repo ครั้งเดียว

{
    "mcpServers": {
        "next-devtools": {
            "command": "npx",
            "args": ["-y", "[email protected]"],
            "env": {
                "NEXT_TELEMETRY_DISABLED": "1"
            }
        }
    }
}

ตั้งแต่ 0.4.0 ตัวนี้เหลือเครื่องมือแค่สี่ตัว

• nextjs_index หา dev server ของ Next 16 ที่รันอยู่ในเครื่อง แล้วบอกว่าแต่ละตัวมีเครื่องมืออะไร ใน monorepo ของเรา agent จึงเห็นทั้งหน้าร้านและ CMS พร้อมกัน
• nextjs_call เรียกเครื่องมือในตารางข้างบนบน dev server ตัวที่เลือก
• nextjs_docs ชี้ agent ไปที่เอกสารใน node_modules/next/dist/docs/ เวอร์ชันก่อนหน้าโหลดเอกสารจากเว็บ แต่ 0.4.0 เปลี่ยนมาใช้ชุดที่มากับ package แทน
• browser_eval แนะนำให้ agent ใช้ agent-browser CLI ของ Vercel เปิดเบราว์เซอร์ดูหน้าเว็บ

เราตั้งไว้สองอย่างที่ต่างจาก README ของตัว package อย่างแรกคือระบุเวอร์ชัน README แนะนำ @latest แต่ 0.4.0 เพิ่งตัดเครื่องมือออกไปหลายตัว ถ้าปล่อยเป็น @latest เครื่องมือที่ agent ใช้อยู่อาจเปลี่ยนไปเองวันไหนก็ได้ ให้ขยับเวอร์ชันเองตอนที่พร้อมดีกว่า อย่างที่สองคือปิด telemetry ตัว package เก็บสถิติการใช้งานแบบไม่ระบุตัวตนเป็นค่าเริ่มต้น ใส่ NEXT_TELEMETRY_DISABLED=1 ไว้ใน env ของ .mcp.json ทุกคนที่เปิด repo นี้จะปิดเหมือนกันหมด โดยไม่ต้องไปตั้งใน .zshrc ของแต่ละเครื่อง

skill ของ Vercel สองตัวที่เรา copy เข้า repo#

Laravel Boost ส่ง skill ของแต่ละ package มาให้ ฝั่ง React และ Next.js มี vercel-labs/agent-skills ที่ Vercel เขียนไว้ เราเลือกมาสองตัว

• react-best-practices กฎเรื่อง performance 70 ข้อ แบ่งเป็นแปดหมวด เช่น await ต่อกันเป็นทอด ๆ ที่ควรรันพร้อมกัน ขนาด bundle การ cache ฝั่ง server และการ render ซ้ำโดยไม่จำเป็น แต่ละข้อเป็นไฟล์ของตัวเอง agent อ่านเฉพาะข้อที่เกี่ยว
• composition-patterns รูปแบบการออกแบบ component เช่น เลิกใช้ boolean prop ที่สลับหน้าตาทั้งก้อน แยกเป็น compound component (<Table> คู่กับ <Table.Toolbar>) และใน React 19 ส่ง ref เป็น prop ธรรมดาได้แล้ว ไม่ต้องใช้ forwardRef

ส่วน skill ของ Next.js เอง Vercel เคยแยกไว้ใน repo next-skills แล้วย้ายออกไปแล้ว next-best-practices เลิกเป็น skill ความรู้ชุดนั้นไปอยู่ในเอกสารที่มากับ package กับบล็อกที่ next dev เขียนให้แทน ส่วน skill ที่เป็นขั้นตอนงานเฉพาะ อย่างลดขนาด bundle หรือเปลี่ยนไปใช้ Cache Components ย้ายไปอยู่ในโฟลเดอร์ skills/ ของ repo Next.js เพื่อให้ตรงเวอร์ชันกับตัว framework เราไม่ได้ติดตั้งพวกนั้น เพราะเหมาะกับงานที่กำลังย้ายระบบไปใช้ feature นั้นมากกว่างานประจำวัน

เราไม่ได้ติดตั้ง skill ผ่านคำสั่งของแต่ละเครื่อง แต่ copy ทั้งโฟลเดอร์เข้า .claude/skills/vercel-* แล้ว commit เข้า repo คนในทีมที่ clone ไปก็ได้ skill ชุดเดียวกันทันที ในแต่ละโฟลเดอร์มีไฟล์ SOURCE.md จดไว้สามเรื่อง คือ copy มาจาก commit ไหนของ repo ต้นทาง (ทั้งสองตัวเป็น MIT) แก้อะไรไปบ้าง ซึ่งเราแก้น้อยที่สุด มีแค่จัดรูปแบบ description ให้ผ่านตัวตรวจ skill ของเรา และวิธีอัปเดตรอบหน้า คือ copy ไฟล์ชุดเดิมจาก commit ใหม่ ใส่การแก้เดิมกลับเข้าไป แล้วเปลี่ยน commit ใน SOURCE.md

เทียบกับ Laravel Boost ทีละส่วน#

ส่วนที่ Next ยังไม่มีให้คือเครื่องมือดูฐานข้อมูล Boost มี Database Schema กับ Database Query ให้ agent ดูตารางจริงได้ ฝั่ง Next ขึ้นกับว่าโปรเจกต์ใช้ ORM ตัวไหน ส่วนเอกสารก็ครอบคลุมแค่ตัว Next เอง ไม่รวม library อื่นในโปรเจกต์อย่างที่ Search Docs ของ Boost ทำ

.ai/rules ฝั่งนี้ไม่มี Boost มาสร้าง index ให้ เราจึงใส่บรรทัดสั้น ๆ ใน CLAUDE.md ชี้ไปที่ไฟล์ rule แต่ละเรื่อง แต่ละไฟล์ยังมี paths ใน front matter บอกว่าใช้กับโฟลเดอร์ไหน เรื่องที่ผูกกับโฟลเดอร์เดียว เช่น ข้อควรระวังของ schema หรือคำสั่งรัน test เฉพาะโฟลเดอร์ ใส่เป็น CLAUDE.md ในโฟลเดอร์นั้นแทน Claude Code อ่านไฟล์นี้เองเมื่อทำงานในโฟลเดอร์นั้น CLAUDE.md ที่ root จึงสั้นลง หลักคิดเรื่องว่าอะไรควรเป็น rule อะไรควรเป็นเอกสาร ใช้แบบเดียวกับที่เล่าไว้ในวิธีเก็บความรู้ของโปรเจกต์ให้ AI agent

สิ่งที่เราเติมเองให้ฝั่ง React#

Boost ไม่มีอะไรบอกว่าไฟล์ไหนใหญ่เกินจนควรแยก ฝั่ง Next ก็ไม่มี ข้อนี้เราจึงเขียนเองเป็น skill react-refactor ในโฟลเดอร์ .claude/skills/ มีสามส่วน

• script ตรวจขนาด อ่านไฟล์ .ts/.tsx ที่เปลี่ยนเทียบกับ branch หลัก แล้วบอกว่าไฟล์ไหนเพิ่งข้ามเกณฑ์ หรือโตขึ้นทั้งที่เกินอยู่แล้ว CI รันตัวเดียวกันและให้ PR ไม่ผ่านถ้าเจอสองกรณีนี้ เกณฑ์แต่ละข้อมีอยู่ในวิธีตั้งเกณฑ์ขนาดไฟล์และ component ใน React
• ขั้นตอนแยกไฟล์ ที่พิสูจน์ได้ว่าพฤติกรรมไม่เปลี่ยน อยู่ในบทวิธี refactor component React ที่ใหญ่เกินด้วย Claude Code
• pattern ที่ใช้แยก พร้อมที่มาของแต่ละข้อ ซึ่งบทอื่นในชุดนี้อธิบายทีละเรื่อง

ส่วนนี้ Laravel ไม่มีให้เหมือนกัน ถ้าโปรเจกต์ Laravel ของเรามีไฟล์ที่โตเรื่อย ๆ ก็ใช้หลักเดียวกันได้

ของทั้งหมดอยู่ใน repo#

ทุกอย่างในบทนี้ commit เข้า repo ทั้ง .mcp.json บล็อกใน AGENTS.md skill ของ Vercel skill ของเรา และ rule คนในทีมที่ clone ไปเปิดด้วย Claude Code ก็ได้ของชุดเดียวกัน ไม่ต้องติดตั้งอะไรเพิ่มในเครื่องตัวเอง ยกเว้นเปิด dev server ตอนอยากให้ agent ดู error

agent จึงรู้ว่าโปรเจกต์ใช้ Next เวอร์ชันไหน อ่านเอกสารของเวอร์ชันนั้นได้ และเห็น error ของหน้าที่เรากำลังทำ ส่วนการตัดสินใจว่าจะเขียนอะไรและ review งานก่อน merge ยังเป็นงานของเราเหมือนตอนใช้ Boost ครับ