กฎสำคัญ: CLI สร้างข้อมูลจริง, AI Model ทำงานบนข้อมูลจริง

นี่เป็นบทความชุดที่ 10 ตอน แบ่งปันประสบการณ์การพัฒนา Apidog CLI เครื่องมือ command-line สำหรับการทดสอบ API และการจัดการ lifecycle ของ API อ่านตามลำดับหรือข้ามไปบทความที่คุณสนใจ:

	หัวข้อ	จุดเน้น
1	เราสร้าง 126 MCP Tools แต่ไม่ใช่ทางเลือกที่ดีที่สุดสำหรับ Agent	การค้นพบปัญหา
2	ทำไมเราพัฒนา Apidog CLI รุ่นใหม่	การพัฒนา architecture
3	กฎสำคัญ: CLI สร้างข้อมูลจริง, AI Model ทำงานบนข้อมูลจริง	หลักการพื้นฐาน
4	`agentHints`: สอน CLI ให้คุยกับ Agents	Structured output
5	SKILL: Ship ประสบการณ์การใช้งานเป็น Code	ประสบการณ์การใช้งาน
6	ตัวเลขไม่โกหก: 30% ลด Tool Calls, 25% ลด Tokens	ผลลัพธ์เชิงตัวเลข
7	จาก PRD ถึง Testing Loop: Agent Workflow สมบูรณ์กับ Apidog CLI	Tutorial ปฏิบัติ
8	ทำไม CI/CD Compatibility จำเป็นสำหรับ Agent Tools	มุมมอง DevOps
9	AI Branch: เปลี่ยนแปลง Project อย่างปลอดภัยกับ AI Agents	Security layer
10	Spec-First เป็นอดีตแล้ว มา Skill-First กัน	วิสัยทัศน์ & อนาคต

ไม่ต้องให้โมเดลจำกฎทุกอย่าง—ให้กฎถูกดำเนินการในจุดที่เหมาะสม cli-schema validate เปลี่ยน Schema จากความรู้ที่ต้องจำ เป็นประตูคุณภาพที่ต้องผ่าน

หลักการหลัก: ให้กฎถูกประมวลผล ณ ที่ที่เหมาะสม

เราสกัดหลักการหลักหนึ่งจากประสบการณ์ของเรา:

อย่าให้ model จดจำกฎทั้งหมด ให้กฎถูกประมวลผล ณ ที่ที่เหมาะสม

นี่คล้ายกับบทเรียนจากการประเมิน Agent:

ประเภทตัวชี้วัด	ที่ที่ควรอยู่
ตัวชี้วัดที่แน่นอน	Scripts, code, automated checks
การตัดสินเชิงความหมาย	LLMs, model reasoning

ใน Apidog CLI + SKILL:

อะไร	ที่ไหน
การตรวจสอบโครงสร้างที่แน่นอน	CLI (cli-schema)
การตัดสินงานและการสร้างเนื้อหา	Agents

ให้ CLI ตรวจสอบโครงสร้าง ให้ Agents สร้างเนื้อหา

ปัญหากับ Model Memory

เมื่อ AI Agent ช่วยสร้างหรืออัปเดต Apidog resources ส่วนที่เสี่ยงไม่ใช่แค่การสร้างเนื้อหา

ส่วนที่เสี่ยงคือการเขียนเนื้อหาที่สร้างขึ้นลงในโปรเจกต์จริงโดยไม่มีโครงสร้างหรือการตรวจสอบเพียงพอ

Apidog resources มีโครงสร้าง ลองพิจารณาว่า test case หรือ test scenario ประกอบด้วยอะไร:

องค์ประกอบ	ความซับซ้อน
Request data	Method, URL, headers, body, auth
Assertions	Comparator, subject, target value, conditions
Variable extraction	Variable name, type, extraction path
Pre-processors	Scripts ก่อน request
Post-processors	Scripts หลัง response
ลำดับขั้นตอน	Sequence, dependencies
Environment references	Environment ID, variable overrides

ถ้า Agent เดาโครงสร้าง:

ชื่อ field ผิด → Write ล้มเหลว
ค่า enum ไม่ถูกต้อง → Server ปฏิเสธ
ขาด field ที่จำเป็น → Resource ไม่สมบูรณ์
Type ผิด → ปัญหาการแสดงผลใน UI
การซ้อนทับไม่ถูกต้อง → Tests ทำงานไม่ตามที่คาด

`cli-schema validate`: ประตูคุณภาพ

การแสดงออกโดยตรงที่สุดของหลักการของเราคือ cli-schema validate

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

เมื่อ Agent ต้องการเขียนหรืออัปเดต test scenario การให้ AI สร้างโครงสร้างขั้นตอนที่ซับซ้อนมีโอกาสผิดพลาดสูงมาก

คำสั่ง validate:

ยืนยันชื่อ fields
ตรวจสอบความถูกต้องของโครงสร้าง
ตรวจสอบความถูกต้องของค่า enum
ตรวจสอบข้อจำกัดของ type

ทั้งหมดก่อนเริ่มต้น write request

ข้อผิดพลาดทั่วไปที่ cli-schema จับได้

นี่คือตัวอย่างจริงของข้อผิดพลาดที่ Agents มักทำ—และ cli-schema validate จับได้:

ค่าผิด	ค่าถูก	บริบท
`global`	`globals`	Variable scope type
`contains`	`include`	Assertion comparator
`responseBody`	`responseJson`	Response body subject
`"500"` (string)	`500` (number)	Delay in milliseconds
`equals`	`equal`	Assertion comparator
`header`	`headers`	Request headers field

เหล่านี้ไม่ใช่ทฤษฎี เราค้นพบพวกมันผ่านการโต้ตอบกับ Agent จริง

แต่ละข้อผิดพลาดจะทำให้:

Write request ล้มเหลว
API error response
Agent สับสนว่าอะไรผิดพลาด
ลองใหม่หลายครั้ง
เสีย tokens กับการเรียกซ้ำๆ

ด้วย cli-schema validate ข้อผิดพลาดเหล่านี้ถูกจับ ภายใน, ก่อน network call

ปรัชญาการออกแบบ

ลองพิจารณาทางเลือกอื่น:

ทางเลือก 1: เขียนกฎลงใน Prompt

ถ้าเราเขียนกฎทุก field ลงใน prompt ของ Agent:

ชื่อ field ทุกตัวถูกบันทึกไว้
ค่า enum ทุกค่าถูกระบุไว้
ข้อจำกัด type ทุกอันถูกอธิบาย
โครงสร้างซ้อนทับทุกอันถูกอธิบาย

ผลลัพธ์: ภาระ context มหาศาล

Schema ของ test scenario ที่ครอบคลุมอาจต้องการ 5,000+ tokens ของคำอธิบาย นั่นคือ context ที่ model ต้องแบกสำหรับทุก task แม้เมื่อกฎส่วนใหญ่ไม่เกี่ยวข้อง

ทางเลือก 2: พึ่ง Model Memory

ถ้าเราพึ่ง model ที่จะ "รู้" โครงสร้างที่ถูกต้อง:

Model ถูก train บนรูปแบบ API บางอัน
แต่ไม่ใช่โดยเฉพาะบน Apidog schemas
ชื่อ field แตกต่างกันในแต่ละ product
ค่า enum เป็นเฉพาะ product

ผลลัพธ์: อัตราข้อผิดพลาดสูง

Model ไม่มีความจำที่สมบูรณ์ของ Apidog-specific conventions มันจะเดา—และการเดาจะผิด

แนวทางที่ดีกว่า: ตรวจสอบภายใน

ให้ Agent สร้าง drafts ให้ CLI ตรวจสอบก่อนเขียน

# Agent สร้าง JSON
# (Agent ไม่จำเป็นต้องจดจำกฎทั้งหมด)

# CLI ตรวจสอบ
apidog cli-schema validate test-case-create --file ./test-case-create.json

# CLI แสดงข้อผิดพลาดเฉพาะถ้ามี
# Agent ปรับตามข้อผิดพลาด

# เฉพาะ writes ที่ถูกต้องดำเนินการ
apidog test-case create --project <projectId> --file ./test-case-create.json

การเปลี่ยนแปลงของ Schema

cli-schema validate เปลี่ยนความหมายของ Schema:

ก่อน	หลัง
Schema = ความรู้ที่ model ต้องจดจำ	Schema = ประตูคุณภาพที่ต้องผ่าน
ข้อผิดพลาดถูกค้นพบผ่าน writes ที่ล้มเหลว	ข้อผิดพลาดถูกค้นพบผ่านการตรวจสอบภายใน
ลองใหม่ผ่าน network calls	แก้ไขผ่านการปรับปรุงภายใน
ภาระ context	ประตู execution

ปัญหาไม่ถูกบริโภคใน network requests ไปมาอย่างไร้ความหมาย

การตรวจสอบคุณภาพเสร็จสิ้นผ่านคำสั่งภายใน

ตัวอย่างการปฏิบัติ

ลองดู workflow จริง:

# Agent อ่าน endpoint
apidog endpoint get <endpointId> --project <projectId>

# Agent สร้าง test case JSON
# (สร้าง ./test-case-create.json)

# ตรวจสอบก่อนเขียน
apidog cli-schema validate test-case-create --file ./test-case-create.json

ถ้าการตรวจสอบผ่าน:

apidog test-case create --project <projectId> --file ./test-case-create.json

ถ้าการตรวจสอบล้มเหลว:

Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local

Suggestion: Fix these fields and re-validate before writing.

Agent:

อ่านข้อผิดพลาดเฉพาะ
เข้าใจว่าอะไรผิดพลาด
ปรับไฟล์ JSON
รันการตรวจสอบใหม่
ดำเนินการเฉพาะเมื่อถูกต้อง

ไม่มี writes ที่ล้มเหลว ไม่มี retries ที่สับสน ไม่มี tokens เสียเปล่า

บทเรียนที่กว้างขึ้น

หลักการนี้ขยายไปไกลกว่าการตรวจสอบ

ประเภทกฎ	ที่ที่ควรอยู่
กฎชื่อ field	cli-schema
กฎค่า enum	cli-schema
ข้อจำกัด type	cli-schema
ลำดับ workflow	SKILL
คำแนะนำขั้นตอนถัดไป	agentHints
การแยก task	Agent

กฎที่แน่นอน → ระบบวิศวกรรม

การตัดสินเชิงความหมาย → Agent

ต่อไปคืออะไร

ตอนนี้เราได้สร้างหลักการตรวจสอบแล้ว คำถามต่อไปคือ:

หลังจากการตรวจสอบ CLI แนะนำ Agent ไปยังขั้นตอนถัดไปอย่างไร?

ในตอนที่ 4, agentHints: Teaching CLIs to Talk to Agents เราจะสำรวจว่า structured output กับ next-step suggestions เปลี่ยน CLI จาก command executor ให้เป็น workflow navigator อย่างไร

สรุปประเด็นสำคัญ

หลักการหลัก: กฎอยู่ใน execution ไม่ใช่ใน context
cli-schema validate เป็นประตูคุณภาพก่อนเขียน
ข้อผิดพลาดทั่วไป: ชื่อ field ผิด, enum ไม่ถูกต้อง, type ผิด
การตรวจสอบจับข้อผิดพลาดภายใน ประหยัด network round-trips
Schema เปลี่ยนจาก "ความรู้ที่จดจำ" เป็น "ประตูที่ต้องผ่าน"
กฎที่แน่นอน → วิศวกรรม; การตัดสินเชิงความหมาย → Agent

ดาวน์โหลด Apidog เพื่อ design, mock, test, และ document APIs ใน workspace. เดียว เรียนรู้เพิ่มเติมเกี่ยวกับ Apidog CLI สำหรับ command-line API testing, CI automation, และ AI Agent workflows.

button