เขียนไฟล์ Instructions ระดับ Repo กับสั่งทุกครั้งในแชท AI ต่างกันตรงไหน

ทีมพัฒนาที่เริ่มใช้ AI coding agent จริงจังมักเจอปัญหาเดียวกันหลังผ่านไปสักพัก คือต้องพิมพ์อธิบายบริบทเดิมซ้ำแล้วซ้ำอีกทุกครั้งที่เปิดแชทใหม่ ตั้งแต่ 'โปรเจกต์นี้ใช้ TypeScript แบบ strict', 'ห้ามแก้ไฟล์ config โดยไม่ถาม', ไปจนถึง 'ชื่อฟังก์ชันต้องเป็น camelCase ไม่ใช่ snake_case' คำอธิบายพวกนี้ไม่ควรต้องพิมพ์ใหม่ทุกรอบ

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

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

Repository Instructions คืออะไร และทำไม Agent ถึงต้องพึ่งไฟล์นี้

ไฟล์ instructions ระดับ repo คือไฟล์ข้อความ (มักเป็น Markdown) ที่วางไว้ในตำแหน่งที่เครื่องมือ AI coding agent แต่ละตัวกำหนดไว้ให้อ่านอัตโนมัติ เช่นวางไว้ที่ root ของ repo หรือในโฟลเดอร์ .github/ ขึ้นอยู่กับเครื่องมือที่ทีมใช้ เนื้อหาข้างในบอกว่าโปรเจกต์นี้มีโครงสร้างอย่างไร ใช้ convention แบบไหน มีข้อห้ามอะไร และอยากให้ agent ทำงานในลักษณะไหนเป็นค่าเริ่มต้น

เหตุผลที่ agent ต้องพึ่งไฟล์นี้คือ context window ของ agent ไม่ได้จำเรื่องที่คุณเคยอธิบายไว้ในแชทก่อนหน้าโดยอัตโนมัติ ทุกครั้งที่เปิดแชทใหม่หรือมอบ task ใหม่ agent เริ่มจากศูนย์เสมอ ยกเว้นมีไฟล์ที่มันถูกออกแบบให้อ่านก่อนเริ่มงานเสมอ ไฟล์ instructions จึงทำหน้าที่เป็น 'ความจำถาวร' ของโปรเจกต์แทนความจำของแชทที่หายไปทุกครั้ง

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

เขียนไฟล์ระดับ Repo กับสั่งในแชททุกครั้ง ต่างกันตรงไหนจริง ๆ

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

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

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

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

ไฟล์ประเภทไหนที่เครื่องมือแต่ละตัวอ่านจริง

เครื่องมือ AI coding agent แต่ละตัวกำหนดตำแหน่งและชื่อไฟล์ instructions ต่างกัน บางตัวอ่านจากไฟล์ในโฟลเดอร์ .github/ บางตัวอ่านจากไฟล์ที่ root ของ repo และบางตัวรองรับไฟล์เฉพาะของตัวเองที่เครื่องมืออื่นไม่อ่าน ก่อนเขียนไฟล์จึงต้องตรวจเอกสารของเครื่องมือที่ทีมใช้จริงว่าอ่านจากตำแหน่งไหน ไม่ใช่เดาจากชื่อไฟล์ที่เคยเห็นในโปรเจกต์อื่น

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

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

เนื้อหาแบบไหนที่ควรใส่ให้ Agent เข้าใจมาตรฐานโปรเจกต์จริง

เนื้อหาที่มีประโยชน์ที่สุดคือสิ่งที่ agent เดาไม่ได้จากการอ่านโค้ดอย่างเดียว เช่นเหตุผลเบื้องหลังการตัดสินใจสถาปัตยกรรม (ทำไมถึงเลือกโครงสร้างโฟลเดอร์แบบนี้), ข้อจำกัดทางธุรกิจที่ไม่ปรากฏในโค้ด (เช่นห้ามแก้ schema ตารางนี้เพราะมีระบบอื่นพึ่งพาอยู่), และคำสั่งที่ต้องรันเพื่อทดสอบหรือ build ให้ตรงกับที่ทีมใช้จริง

อีกส่วนที่ควรใส่คือรูปแบบ commit message, กติกาการตั้งชื่อ branch, และขอบเขตที่ agent ทำได้เองกับสิ่งที่ต้องถามก่อนเสมอ เช่น 'แก้ dependency version ได้เอง แต่ห้ามลบไฟล์ migration โดยไม่ถาม' คำสั่งแบบนี้ช่วยลดความเสี่ยงจาก agent ที่ทำงานแบบ autonomous ได้มากกว่าการเขียนกฎ style code ทั่วไปเสียอีก

ควรใส่ลิงก์อ้างอิงไปยังเอกสารเชิงลึกที่มีอยู่แล้วของทีม เช่นเอกสารสถาปัตยกรรมหรือคู่มือการทำงานร่วมกับ Agent Skills แทนที่จะคัดลอกเนื้อหาทั้งหมดมาไว้ในไฟล์ instructions ซึ่งจะทำให้ไฟล์ยาวเกินไปและดูแลยากขึ้นเรื่อย ๆ

สิ่งที่ไม่ควรใส่ เพราะทำให้ Agent สับสนหรือเสี่ยงมากขึ้น

ไม่ควรใส่ secret, token หรือ credential ใด ๆ ในไฟล์ instructions แม้จะดูเหมือนช่วยให้ agent ทดสอบได้ง่ายขึ้น เพราะไฟล์นี้มักถูก commit เข้า repo และอาจถูกอ่านโดยใครก็ตามที่เข้าถึง repo ได้ รวมถึงกรณีที่ agent เอง log เนื้อหาไฟล์ออกมาระหว่างทำงานโดยไม่ตั้งใจ

ไม่ควรใส่กฎที่ขัดแย้งกันเองในไฟล์เดียว เช่นบอกว่า 'ใช้ function component เสมอ' ในส่วนหนึ่ง แต่อีกส่วนอ้างอิงตัวอย่างที่เป็น class component เก่า ความขัดแย้งแบบนี้ทำให้ agent เลือกทำตามกฎไหนก็ได้ ซึ่งมักเลือกผิดเวลาที่ทีมต้องการมากที่สุด

ไม่ควรใส่คำสั่งที่กว้างเกินจนตีความได้หลายแบบ เช่น 'เขียนโค้ดให้ดี' หรือ 'ทำตามมาตรฐานอุตสาหกรรม' คำสั่งแบบนี้ไม่ได้ให้ข้อมูลอะไรที่ agent ใช้ตัดสินใจได้จริง ควรเขียนเป็นกฎที่ตรวจสอบได้ เช่นระบุ lint rule หรือ pattern ที่ต้องการเป็นตัวอย่างจริงแทน

ตารางเทียบสามแนวทางที่ทีมใช้ให้บริบทกับ Agent

ตารางนี้เทียบสามแนวทางที่ทีมส่วนใหญ่ใช้ผสมกันในทางปฏิบัติ ไม่มีแนวทางไหนที่ใช้แทนอีกสองแนวทางได้ทั้งหมด:

รักษาไฟล์ให้ตรงกับโค้ดจริงเมื่อโปรเจกต์เปลี่ยนไปเรื่อย ๆ

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

แนวทางที่ช่วยได้คือผูกการอัปเดตไฟล์ instructions เข้ากับ pull request ที่เปลี่ยนโครงสร้างสำคัญ เช่นถ้า PR เปลี่ยน convention การตั้งชื่อไฟล์ ให้ต้องแก้ไฟล์ instructions ในรอบเดียวกัน ไม่ปล่อยให้เป็นงานแยกที่ทำทีหลัง ซึ่งมักไม่มีใครทำจริง

บางทีมใช้ workflow ใน GitHub Actions ช่วยเตือนเมื่อไฟล์ config หลักเปลี่ยนแต่ไฟล์ instructions ไม่ได้ถูกแก้ในรอบเดียวกัน วิธีนี้ไม่ได้บังคับให้แก้ทันที แต่ช่วยเตือนไม่ให้ไฟล์ล้าสมัยไปเรื่อย ๆ โดยไม่มีใครสังเกต

ทีมที่ใช้หลาย Agent พร้อมกัน ไฟล์เดียวพอไหมหรือต้องแยก

ทีมที่ใช้ทั้ง Copilot สำหรับงานระหว่างเขียนโค้ด และ agent อีกตัวสำหรับงานมอบหมายเป็นชิ้นแบบที่กล่าวถึงใน การต่อ GitHub MCP Server มักถามว่าต้องเขียนไฟล์ instructions แยกกันหรือใช้ไฟล์เดียวพอ คำตอบขึ้นกับว่ากฎที่ต้องการสื่อสารเป็นกฎร่วมของทั้งโปรเจกต์หรือกฎเฉพาะของเครื่องมือใดเครื่องมือหนึ่ง

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

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

จุดพลาดที่ทำให้ไฟล์ Instructions ไม่ช่วยอะไรเลย

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

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

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

สรุป

ไฟล์ instructions ระดับ repo กับการสั่งในแชททุกครั้งไม่ได้แข่งกัน แต่ทำหน้าที่ต่างกัน ไฟล์นี้เหมาะกับกฎถาวรที่ agent ต้องรู้ทุกครั้งไม่ว่าใครจะเป็นคนเปิดงาน ส่วนคำสั่งในแชทยังจำเป็นสำหรับรายละเอียดเฉพาะของ task ที่กำลังทำอยู่

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

• ไฟล์ instructions คงที่และมีผลกับทุก task ส่วนคำสั่งในแชทหายไปเมื่อจบการสนทนา ใช้เสริมกัน
• เขียนเฉพาะสิ่งที่ agent เดาไม่ได้จากโค้ด หลีกเลี่ยง secret และกฎที่ขัดแย้งกันเอง
• ผูกการอัปเดตไฟล์เข้ากับ PR ที่เปลี่ยนโครงสร้างสำคัญ เพื่อไม่ให้ไฟล์ล้าสมัยโดยไม่มีใครรู้ตัว

คำถามที่พบบ่อย