วิธีเขียน `Claude.md` ที่ดี

 (humanlayer.dev)
78 คะแนน โดย GN⁺ 2025-12-01 | 1 ความคิดเห็น | แชร์ทาง WhatsApp
  • เนื่องจาก LLM เป็นฟังก์ชันที่ไม่เก็บสถานะ CLAUDE.md จึงทำหน้าที่เป็นเอกสารหลักที่ใช้แนะนำโค้ดเบสให้ Claude ในทุกเซสชัน
  • ภายในไฟล์ควรสรุป WHAT (โครงสร้าง), WHY (จุดประสงค์) และ HOW (วิธีการทำงาน) ของโปรเจ็กต์อย่างกระชับ โดยการใส่คำสั่งที่ไม่จำเป็นมากเกินไปจะทำให้ประสิทธิภาพลดลง
  • Claude อาจ เพิกเฉย ต่อเนื้อหาใน CLAUDE.md ได้ หากตัดสินตามคำสั่งใน system message แล้วเห็นว่า ไม่เกี่ยวข้องมากพอ
  • ไฟล์ที่มีประสิทธิภาพควรมีเพียง ข้อมูลสั้น ๆ ที่ใช้ได้ทั่วไป เท่านั้น และแยกคำแนะนำรายละเอียดไปไว้ในเอกสารอื่นเพื่อจัดการแบบ Progressive Disclosure
  • CLAUDE.md คือ จุดที่มีอิทธิพลสูงสุดของ agent harness จึงควรเขียนด้วยมืออย่างรอบคอบแทนการสร้างอัตโนมัติ

ความไร้สถานะของ LLM และบทบาทของ CLAUDE.md

  • LLM ใช้ ค่าน้ำหนักที่ตรึงไว้ ณ เวลาที่ทำการอนุมาน และไม่ได้เรียนรู้หรือจดจำข้ามเซสชัน
    • ดังนั้นหากต้องการให้โมเดลเข้าใจโค้ดเบส ก็ต้องป้อนข้อมูลทั้งหมดผ่าน input token
  • เอเจนต์เขียนโค้ดอย่าง Claude Code จำเป็นต้องจัดการหน่วยความจำอย่างชัดเจน และ CLAUDE.md คือ ไฟล์เดียวที่ถูกแนบให้อัตโนมัติในทุกบทสนทนา
  • จึงมี 3 ข้อที่สำคัญ
    1. เมื่อเริ่มเซสชัน Claude ไม่รู้อะไรเกี่ยวกับโค้ดเบสมาก่อน
    2. จำเป็นต้องบอกข้อมูลที่ต้องใช้ใหม่ในทุกเซสชัน
    3. เครื่องมือมาตรฐานสำหรับสิ่งนี้คือ CLAUDE.md

การออนบอร์ดโค้ดเบส: WHAT, WHY, HOW

  • CLAUDE.md ทำหน้าที่เป็น เอกสารออนบอร์ด ที่ช่วยให้ Claude เข้าใจโปรเจ็กต์
    • WHAT: ให้แผนที่ของโค้ด เช่น tech stack, โครงสร้างโปรเจ็กต์, องค์ประกอบของ monorepo
    • WHY: อธิบายจุดประสงค์และหน้าที่ของแต่ละองค์ประกอบ
    • HOW: ระบุวิธีทำงานจริง เช่น build, test, typecheck
  • อย่างไรก็ตาม การไล่รายการคำสั่งทั้งหมดเป็นวิธีที่ไม่มีประสิทธิภาพ และควรใส่เฉพาะ ข้อมูลขั้นต่ำที่จำเป็น เท่านั้น

เหตุผลที่ Claude อาจมองข้าม CLAUDE.md

  • Claude Code จะแทรก system reminder ลักษณะนี้เข้าไปในข้อความของผู้ใช้ 
    IMPORTANT: this context may or may not be relevant...
    • ด้วยเหตุนี้ Claude จึงอาจ ละเลยบริบทนั้น หากเห็นว่า ไม่เกี่ยวข้องกับงานปัจจุบัน
  • ยิ่งไฟล์มี คำสั่งที่ไม่ได้ใช้ได้ทั่วไป มากเท่าไร ก็ยิ่งมีโอกาสถูกมองข้ามมากขึ้นเท่านั้น
  • คาดว่าเหตุผลที่ Anthropic เพิ่มสิ่งนี้เข้ามา เป็นเพราะเมื่อเพิกเฉยต่อคำสั่งที่ไม่จำเป็นแล้ว คุณภาพของผลลัพธ์ดีขึ้น

หลักการเขียน CLAUDE.md ที่ดี

Less (instructions) is more

  • LLM สามารถปฏิบัติตาม คำสั่งได้อย่างเสถียรราว 150~200 ข้อ
    • ยิ่งเป็นโมเดลขนาดเล็ก ประสิทธิภาพจะยิ่งลดลงอย่างรวดเร็ว และไม่เหมาะกับงานหลายขั้นตอน
  • system prompt ของ Claude Code มี คำสั่งอยู่แล้วประมาณ 50 ข้อ
    • ดังนั้นใน CLAUDE.md จึงควรใส่เฉพาะ คำสั่งที่ใช้ได้ทั่วไปและจำเป็นจริง ๆ เท่านั้น
  • ยิ่งจำนวนคำสั่งมากขึ้น คุณภาพในการทำตามคำสั่งทั้งหมดจะลดลงอย่างสม่ำเสมอ

ความยาวไฟล์และขอบเขตการใช้งาน

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

Progressive Disclosure

  • ในโปรเจ็กต์ขนาดใหญ่ เป็นเรื่องยากที่จะใส่ทุกอย่างไว้ในไฟล์เดียว จึงแนะนำแนวทาง Progressive Disclosure
    • แยกคำแนะนำเชิงลึกไปไว้ในไฟล์ Markdown ต่างหากภายใต้โฟลเดอร์ agent_docs/
    • เช่น building_the_project.md, running_tests.md, code_conventions.md เป็นต้น
  • ใน CLAUDE.md ให้ใส่เพียง รายการไฟล์เหล่านี้พร้อมคำอธิบายสั้น ๆ และคำสั่งให้ Claude เปิดอ่านเมื่อจำเป็น
  • ใช้ การอ้างอิงแบบ file:line แทน code snippet เพื่อให้ข้อมูลทันสมัยอยู่เสมอ
  • แนวทางนี้คล้ายกับแนวคิด Claude Skills แต่เน้นที่การจัดการคำสั่งมากกว่าการใช้เครื่องมือ

Claude ไม่ใช่ linter

  • การใส่แนวทางด้าน code style ลงใน CLAUDE.md เป็นวิธีที่ไม่มีประสิทธิภาพ
    • LLM มี ต้นทุนสูง ช้า และให้ผลไม่แน่นอนมากกว่า linter
  • กฎด้านสไตล์มักถูก เรียนรู้ได้เองตามธรรมชาติจากแพตเทิร์นของโค้ดที่มีอยู่ จึงไม่จำเป็นต้องสั่งแยก
  • สำหรับ formatting ควรใช้ linter ที่แก้ไขอัตโนมัติได้ (เช่น Biome) แล้วส่งให้ Claude เฉพาะผลการแก้ไข
  • หากจำเป็น อาจใช้ Stop Hook หรือ Slash Command เพื่อทำ formatting และ validation แบบอัตโนมัติ

ห้ามสร้างอัตโนมัติ

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

บทสรุป

  • CLAUDE.md คือเอกสารสำหรับออนบอร์ด Claude เข้ากับโค้ดเบส และต้องกำหนด WHY·WHAT·HOW ให้ชัดเจน
  • ควร ลดจำนวนคำสั่งให้เหลือน้อยที่สุด และใส่เฉพาะ เนื้อหาที่ใช้ได้ทั่วไปและกระชับ
  • ใช้ Progressive Disclosure เพื่อค่อย ๆ ให้ข้อมูลเท่าที่จำเป็น
  • อย่าใช้ Claude เป็น linter แต่ควรใช้งานร่วมกับ เครื่องมือเฉพาะทาง รวมถึง hook และคำสั่งต่าง ๆ
  • แทนที่จะสร้างอัตโนมัติ ควร เขียนด้วยมืออย่างรอบคอบ เพื่อยกระดับคุณภาพของ harness โดยรวมให้สูงสุด

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2025-12-01
ความคิดเห็นจาก Hacker News

  • Claude มักมีแนวโน้มจะเพิกเฉยต่อคำสั่งใน CLAUDE.md อยู่บ่อย ๆ
    ยิ่งในไฟล์มีข้อมูลที่ไม่เกี่ยวกับงานเฉพาะนั้นมากเท่าไร Claude ก็ยิ่งไม่ทำตามคำสั่งนั้น
    มีคนรู้จักคนหนึ่งบอกให้ Claude เรียกเขาว่า “Mr Tinkleberry” และทุกครั้งที่ Claude ลืม ก็รู้ได้เลยว่ามันกำลังมองข้ามไฟล์นั้นอยู่

  • ฉันใช้ แนวทางแบบสารบัญ มานานแล้ว
    แยกคำแนะนำตามงานไว้ในไฟล์ markdown คนละไฟล์ และใส่ไว้ใน CLAUDE.md แค่รายการกับคำอธิบายสั้น ๆ
    วิธีนี้ช่วยให้ context window สะอาดและเป็นระเบียบ
    ดูไฟล์ตัวอย่างของฉันได้ที่นี่

    • ฉันก็เคยใช้วิธีเดียวกัน แต่ผลลัพธ์ไม่ค่อยสม่ำเสมอ
      Claude แทบไม่ค่อยอ่านไฟล์เอกสารอื่น ๆ จริง ๆ

  • ฉันรู้สึกว่าถ้าให้ context กับ Claude มากเกินไป คุณภาพกลับลดลง
    เลยเก็บโค้ดไว้สองเวอร์ชันเสมอ

    1. โค้ดต้นฉบับที่ไม่มีคอมเมนต์และช่องว่าง
    2. โค้ดที่มีคอมเมนต์
      ฉันให้ LLM แค่เวอร์ชันแรก
      คิดว่าหัวใจสำคัญคือ อัตราส่วนระหว่าง compute ต่อข้อมูล เพราะปริมาณการประมวลผลมีจำกัด
    • ฉันก็มีประสบการณ์คล้ายกัน แต่พอเอาเนื้อหาที่ซ้ำ ๆ ไปใส่ในไฟล์ Claude notes แล้วมีประสิทธิภาพขึ้น
      ไม่จำเป็นต้องใส่ทุกอย่าง แต่การใส่ ข้อมูลสำคัญ ให้ ROI สูงมาก
      Claude ทำงานได้ดีกับโปรเจกต์ทั่วไป แต่กับเฟรมเวิร์กหรือเครื่องมือใหม่ ๆ มักจะสับสนบ่อย
    • คุณบอกว่าเก็บโค้ดสองเวอร์ชัน เลยสงสัยว่าจัดการความสอดคล้องกันอย่างไร
      อยากถามว่าใช้สคริปต์ลบคอมเมนต์กับช่องว่างหลังแก้ไขหรือเปล่า
    • ฉันคิดว่าภายในไฟล์เอกสารควรรักษา ความหนาแน่นของข้อมูล ให้สูง
    • คุณบอกว่าไม่ให้ LLM ดูเวอร์ชันที่มีคอมเมนต์ เลยสงสัยว่าทำแบบนั้นจริง ๆ อย่างไร
    • สุดท้ายแล้ว attention มีจำกัด ถ้าใส่ context มากเกินไป สมาธิก็จะกระจาย

  • จริง ๆ แล้วมีวิธีแก้โดยไม่ต้องตั้งค่าอะไรซับซ้อนแบบนี้
    นั่นคือทำ เอกสารประกอบ(documenting) ให้โค้ดชัดเจน
    เขียนสั้น ๆ ว่าแต่ละไฟล์ทำอะไร เท่านี้มันก็ทำหน้าที่เป็นพรอมป์ต์ได้แล้ว
    ใช้ README.md ให้เต็มที่ก็พอ
    LLM ถูกฝึกจากข้อมูลสาธารณะที่มีอยู่แล้ว จึงไม่จำเป็นต้องประดิษฐ์อะไรใหม่

    • แต่เวลาจะเขียนเอกสารสำหรับ AI ต้องใช้ วิธีที่ต่างจากเอกสารสำหรับผู้อ่านมนุษย์
      การแนะนำแค่ว่า “เขียนเอกสารโค้ดให้ดี” จึงไม่ค่อยตรงกับบริบทนี้
    • ฉันก็คิดว่าชุมชน AI บางทีก็ ประดิษฐ์วงล้อขึ้นใหม่โดยไม่จำเป็น
      README นั้นดี แต่ CLAUDE.md มีจุดประสงค์ต่างออกไป
      ตัวอย่างเช่น Claude/agents.md มีฟีเจอร์ที่จะแทรกเข้า context อัตโนมัติเมื่อเข้าถึงไดเรกทอรีบางแห่ง
      ในโค้ดเบสที่ซับซ้อน การจัดการ context สำคัญกว่ามาก
    • CLAUDE.md ไม่ใช่แค่เอกสารธรรมดา แต่มีหน้าที่ ปรับแต่ง initial prompt ของโมเดล
      ดังนั้นคำแนะนำอย่าง “เขียนพรอมป์ต์ให้เหมาะสม” จึงพลาดประเด็นสำคัญ
    • ตัวอย่างเช่น กฎว่า “database query ต้องใช้อินเด็กซ์เสมอ” ควรเขียนไว้ที่ไหน?
      ถ้าใส่ใน README มันก็จะลงเอยด้วยการทำหน้าที่เหมือน CLAUDE.md
      จุดประสงค์ของ CLAUDE.md คือการ ให้ข้อมูลสำคัญล่วงหน้า เพื่อไม่ให้ Claude ต้องกลับไปอ่านเอกสารทั้งหมดใหม่ทุกครั้ง
      มนุษย์จำได้ แต่ Claude ลืมทุกครั้งเมื่อเริ่มงานใหม่ จึงต้องมีโครงสร้างที่ช่วยลดการ re-onboarding

  • พูดตามตรง ถ้าต้อง ตั้งค่าโครงสร้างพื้นฐาน AI กันขนาดนี้ ฉันรู้สึกว่าสู้เขียนโค้ดเองยังดีกว่า

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

  • ฉันแค่ คัดลอกโค้ดที่ต้องใช้แล้ววางลงในหน้าต่างแชต จากนั้นก็ใช้งานเหมือนคุยกัน
    ทุกวันนี้โมเดลดีขึ้นมากแล้ว ต่อให้ไม่มีไฟล์ .md ก็ยังให้ผลลัพธ์ที่ค่อนข้างดี
    ไฟล์พวกนี้อาจช่วยให้ดีขึ้นได้นิดหน่อย แต่ฉันไม่คิดว่ามันเป็น เวทมนตร์เพิ่มผลิตภาพ 100 เท่า

    • แต่นี่เป็นคนละ use case
      ที่กำลังคุยกันตรงนี้คือกรณีที่ Claude ลงมือทำฟีเจอร์ทั้งก้อนหรือแก้บั๊กเอง
    • ฉันก็มีประสบการณ์คล้ายกัน เคยทำ CLAUDE.md ครั้งหนึ่งแต่ตอนนี้ไม่ใช้แล้ว
      แค่ให้ context ที่จำเป็นก็ทำงานได้ดีพอแล้ว มันดู bikeshedding นิด ๆ
    • ถึงอย่างนั้น ถ้ารวบรวมรายการตารางหรือคอลัมน์ของฐานข้อมูลไว้ล่วงหน้า ก็ช่วยลดงานซ้ำได้

  • ฉันให้ Claude เขียน CLAUDE.md เอง
    ถ้าบอกมันว่า “README.md มีไว้สำหรับผู้ใช้ ส่วน CLAUDE.md มีไว้สำหรับเธอ”
    มันก็จะอัปเดตคำสั่งอย่าง “ให้ตรวจเอกสาร API ก่อนเสมอ” ให้อัตโนมัติด้วย
    ไม่จำเป็นต้องรู้พรอมป์ต์วิเศษอะไร ขอแค่ผลลัพธ์ออกมาดีก็พอ

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