ขั้นตอนการสร้าง spec.md สำหรับ Codex และ Claude Code

• 1. spec.md คืออะไร และช่วยอะไร
• 2. แยกหน้าที่ของไฟล์ให้ชัดเจน
• 3. ขั้นตอนเขียนสเปก 8 ขั้น
  • ขั้นที่ 1: เขียนปัญหา ผู้ใช้ และเป้าหมาย
  • ขั้นที่ 2: กำหนดขอบเขต
  • ขั้นที่ 3: ระบุข้อจำกัดและสภาพแวดล้อม
  • ขั้นที่ 4: เขียน Functional Requirements พร้อมรหัส
  • ขั้นที่ 5: กำหนดข้อมูล สัญญา API หรือ UI
  • ขั้นที่ 6: เขียน Acceptance Criteria และแผนทดสอบ
  • ขั้นที่ 7: ตรวจความขัดแย้งและเรื่องที่ยังไม่ตัดสินใจ
  • ขั้นที่ 8: ให้เอเจนต์อ่าน วางแผน ลงมือ และตรวจรับ
• 4. แม่แบบ spec.md สำหรับคัดลอก
• 5. ตัวอย่าง spec.md: Task API สำหรับ workshop
• 6. เชื่อมสเปกกับ Codex
• 7. เชื่อมสเปกกับ Claude Code
• 8. Prompt ให้ AI ช่วยสร้าง spec.md ตั้งแต่ต้น
• 9. Prompt สำหรับตรวจสเปกและตรวจงาน
  • ตรวจสเปกก่อนพัฒนา
  • ตรวจงานหลังพัฒนา
• 10. Checklist ก่อนส่งให้เอเจนต์พัฒนา
• 11. ข้อผิดพลาดที่พบบ่อย
• 12. แหล่งอ้างอิง

คู่มือภาษาไทยสำหรับใช้ข้อกำหนดนำการพัฒนา พร้อมแม่แบบ ตัวอย่าง และ prompt ที่นำไปปรับใช้ได้

#1. spec.md คืออะไร และช่วยอะไร

spec.md คือเอกสาร Markdown ที่บอกว่า ต้องสร้างอะไร ให้ใคร ใช้เงื่อนไขใด และจะตรวจอย่างไรว่าสำเร็จ ช่วยให้ผู้พัฒนาและ AI coding agent อ้างอิงข้อตกลงเดียวกัน แทนการฝากข้อกำหนดทั้งหมดไว้ในประวัติแชต

ชื่อ spec.md ในบทความนี้เป็นข้อตกลงการจัดเอกสารของโครงการ ไม่ใช่รูปแบบบังคับของ Codex หรือ Claude Code และไม่ควรคาดหวังว่าทั้งสองเครื่องมือจะอ่านไฟล์นี้เองจากชื่อไฟล์เพียงอย่างเดียว ให้ระบุให้อ่านใน prompt หรือคำแนะนำของ repository

OpenAI มีตัวอย่าง workflow ที่ใช้ไฟล์กำหนดเป้าหมายและแผนเพิ่มเติม โดยชี้ชัดว่าไฟล์ประกอบเหล่านั้นเป็นแนวทางจัดงาน ไม่ใช่ไฟล์บังคับของ Codex [1]

ตัวอย่างความต่าง:

สเปกช่วยลดความกำกวม แต่ยังต้องตรวจโค้ดและทดสอบผลลัพธ์จริง

#2. แยกหน้าที่ของไฟล์ให้ชัดเจน

Codex รองรับการค้นหาและอ่าน AGENTS.md ตามขอบเขต directory [2] ส่วน Claude Code รองรับ CLAUDE.md และการ import ไฟล์ด้วย @path [3]

เอกสาร Claude Code ปัจจุบันยังระบุการรองรับ AGENTS.md โดยมีเงื่อนไขตามเวอร์ชันและการตั้งค่า เมื่อมี CLAUDE.md ในลำดับ directory ที่เกี่ยวข้อง ค่าเริ่มต้นอาจเลือกอ่าน CLAUDE.md แทน ดังนั้นตัวอย่างบทความนี้ใช้ CLAUDE.md ที่ import AGENTS.md อย่างชัดเจน [3]

โครงสร้างและแม่แบบต่อจากนี้เป็นข้อเสนอสำหรับ workshop ของบทความ ไม่ใช่มาตรฐานที่ผู้ผลิตบังคับใช้

โครงสร้างเริ่มต้นที่แนะนำ:

เริ่มด้วยไฟล์เท่าที่งานต้องใช้ โครงการใหญ่ค่อยแยกเป็น docs/specs/task-api.md หรือสเปกตาม feature

#3. ขั้นตอนเขียนสเปก 8 ขั้น

#ขั้นที่ 1: เขียนปัญหา ผู้ใช้ และเป้าหมาย

ตอบให้ได้ว่าใครมีปัญหาอะไร และเมื่อส่งมอบแล้วต้องทำอะไรได้

ตัวอย่าง:

ผู้เรียนต้องการ API ขนาดเล็กสำหรับฝึก API Testing สามารถสร้าง ดู แก้ไข และลบงานได้ และข้อมูลยังอยู่หลัง restart โปรแกรม

หากเป็น repository เดิม ให้เอเจนต์อ่านโครงสร้าง README ไฟล์ dependency/lockfile และระบบทดสอบก่อน บันทึกข้อเท็จจริงที่พบแยกจากข้อเสนอใหม่ ห้ามเขียนว่าใช้เทคโนโลยีหรือเวอร์ชันใดโดยยังไม่ได้ตรวจ

#ขั้นที่ 2: กำหนดขอบเขต

ระบุทั้งสิ่งที่ต้องทำและสิ่งที่เลื่อนไปก่อน

ในขอบเขต: CRUD งาน, validation, SQLite persistence, automated tests, README

นอกขอบเขต: บัญชีผู้ใช้, สิทธิ์หลายผู้ใช้, notification, frontend, public deployment

การกำหนดขอบเขตช่วยให้เอเจนต์ตัดสินใจได้ว่าจะเพิ่มส่วนใดได้บ้าง โดยไม่ต้องเดา feature เพิ่มเติม

#ขั้นที่ 3: ระบุข้อจำกัดและสภาพแวดล้อม

เขียนข้อมูลที่มีผลต่อการออกแบบ เช่น:

• ใช้ภาษา framework และ dependency manager ใด
• ต้องรักษา API เดิมหรือรูปแบบข้อมูลเดิมหรือไม่
• runtime และ dependencies ยึดตามไฟล์ใด
• ต้องรันด้วย Docker Compose หรือรันตรงได้
• คำสั่ง lint, test และ build คืออะไร
• ระบบรองรับผู้ใช้และปริมาณข้อมูลประมาณเท่าใด

แยก ข้อจำกัดที่ยืนยันแล้ว ออกจาก ข้อเสนอให้เลือก หากเป็นโครงการใหม่ให้ตกลง stack ก่อนลงมือ และบันทึกเวอร์ชันที่ติดตั้งจริงใน manifest/lockfile

#ขั้นที่ 4: เขียน Functional Requirements พร้อมรหัส

ใช้รหัส เช่น FR-001 เพื่อเชื่อมข้อกำหนดกับ test และผลตรวจรับ

ตัวอย่าง:

• FR-001: สร้างงานด้วย title และ description
• FR-002: แสดงรายการงานตามเวลาสร้างล่าสุดก่อน
• FR-003: เปลี่ยนสถานะงานเป็น done
• FR-004: ลบงานแล้วอ่านซ้ำต้องได้ 404

แต่ละข้อควรมีพฤติกรรมหลัก อินพุต ผลลัพธ์ และกรณีผิดพลาด ไม่จำเป็นต้องกำหนดวิธีเขียนโค้ดทุกบรรทัด

#ขั้นที่ 5: กำหนดข้อมูล สัญญา API หรือ UI

สำหรับ API ให้ระบุ method, path, request, response, status code, validation, pagination และ error format

สำหรับ UI ให้ระบุหน้าจอ การกระทำของผู้ใช้ empty/loading/error state และผลหลังบันทึก รวมถึงสิทธิ์เข้าถึงเมื่อเกี่ยวข้อง

ตัวอย่างรายละเอียดที่มักตกหล่น:

• ช่องว่างล้วนถือว่าเป็น title ว่างหรือไม่
• ความยาวข้อความนับ bytes, code points หรือ grapheme clusters
• PATCH ที่ส่งค่าเดิมจะมีผลอย่างไร
• id ที่ไม่มีอยู่ต่างจาก id ที่ผิดรูปแบบอย่างไร
• ค่า null กับการไม่ส่ง field มีความหมายเหมือนกันหรือไม่
• เมื่อบันทึกข้อมูลไม่สำเร็จ จะตอบอะไร

#ขั้นที่ 6: เขียน Acceptance Criteria และแผนทดสอบ

Acceptance criteria คือเงื่อนไขตรวจรับที่สังเกตผลได้ เช่น:

Given มีงาน id=1 ที่ status เป็น todo
When ส่ง PATCH /api/v1/tasks/1 ด้วย {"status":"done"}
Then ได้ HTTP 200
And response มี status เป็น done
And GET /api/v1/tasks/1 ยังได้ status เป็น done

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

#ขั้นที่ 7: ตรวจความขัดแย้งและเรื่องที่ยังไม่ตัดสินใจ

ตรวจว่าขอบเขต ข้อมูล API และเกณฑ์ตรวจรับสอดคล้องกัน

ใช้สถานะต่อไปนี้ได้:

• Confirmed: ตกลงแล้ว
• Assumption: สมมติฐานที่ระบุผลกระทบไว้
• Open question: เรื่องที่ต้องตัดสินใจ

อย่าให้เอเจนต์เปลี่ยนข้อสงสัยเป็นข้อกำหนดโดยไม่บอก หากเรื่องนั้นมีผลต่อ schema, สิทธิ์, API contract หรือขอบเขตหลัก ให้ตัดสินใจก่อนพัฒนาส่วนที่เกี่ยวข้อง

#ขั้นที่ 8: ให้เอเจนต์อ่าน วางแผน ลงมือ และตรวจรับ

แบ่งงานเป็น feature หรือ milestone ที่ตรวจจบได้ ให้แต่ละรอบอ้างอิง requirement IDs และ acceptance criteria

แนวทางสำรวจ วางแผน แล้วจึงพัฒนาสอดคล้องกับคำแนะนำของ Claude Code โดยควรให้เอเจนต์แสดงหลักฐานการตรวจสอบด้วย [4]

#4. แม่แบบ spec.md สำหรับคัดลอก

คัดลอกบล็อกนี้เป็นไฟล์ spec.md แล้วแทนที่ข้อความในวงเล็บ หลีกเลี่ยงการส่งสเปกที่ยังมี placeholder สำคัญให้เอเจนต์เริ่มเขียนโค้ด

# [ชื่อโครงการหรือ Feature]

- Status: Draft
- Version: 0.1
- Owner: [ผู้ตัดสินใจ]
- Updated: [YYYY-MM-DD]

## 1. Problem and Goal
- ปัญหา:
- ผู้ใช้:
- ผลลัพธ์ที่ต้องการ:

## 2. Scope
### In scope
- ...

### Out of scope
- ...

## 3. Existing Context and Constraints
- Repository / baseline:
- Existing architecture:
- Runtime / dependencies / lockfile:
- Compatibility:
- Environment:
- Confirmed constraints:

## 4. Functional Requirements
| ID | Requirement | Priority |
| --- | --- | --- |
| FR-001 | [พฤติกรรมที่ตรวจสอบได้] | Must |

## 5. Data Model
| Field | Type | Required | Rule |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

## 6. API / UI Contract
- Interface:
- Request / input:
- Response / output:
- Validation:
- Error states:
- Authentication / authorization:

## 7. Quality Requirements
- Security and privacy:
- Reliability:
- Performance target and measurement environment:
- Accessibility, if applicable:

## 8. Acceptance Criteria
### AC-001 — [ชื่อ] — covers FR-001
- Given:
- When:
- Then:

## 9. Verification
- Setup command:
- Lint command:
- Test command:
- Build command:
- Manual checks:
- Required evidence:

## 10. Delivery and Definition of Done
- [ ] Requirements ในขอบเขตครบ
- [ ] ผ่าน acceptance criteria
- [ ] รัน checks ที่เกี่ยวข้องและบันทึกผล
- [ ] มีคู่มือเริ่มต้น
- [ ] ระบุข้อจำกัดและสิ่งที่ยังตรวจไม่ได้

## 11. Assumptions and Open Questions
- Assumptions:
- Open questions:
- Blocking decisions:

## 12. Change Log
- YYYY-MM-DD: สร้างฉบับร่าง

หากหัวข้อใดไม่เกี่ยวข้อง ให้เขียนเหตุผลสั้น ๆ หรือเอาออก แทนการเติมข้อกำหนดที่ไม่ช่วยตัดสินใจ

#5. ตัวอย่าง spec.md: Task API สำหรับ workshop

ตัวอย่างนี้ตั้งใจใช้บนเครื่องผู้เรียนเท่านั้น เพื่อให้ขอบเขตเล็กและตรวจรับได้ครบ เทคโนโลยีเป็นตัวอย่างประกอบ สามารถแทนที่ด้วย Laravel, Spring Boot หรือ stack ของ repository โดยปรับคำสั่งและรายละเอียดให้ตรงกัน

# Local Task API

- Status: Ready for implementation
- Version: 1.0
- Updated: 2026-10-17

## 1. Goal

สร้าง REST API สำหรับฝึก API Testing บนเครื่องผู้เรียน
รองรับการจัดการงาน และเก็บข้อมูลไว้หลัง restart โปรแกรม

## 2. Scope

In scope:
- สร้าง แสดงรายการ อ่าน แก้ไข และลบงาน
- ตรวจสอบ input และตอบ error ตามรูปแบบเดียวกัน
- เก็บข้อมูลด้วย SQLite
- มี integration tests และ README

Out of scope:
- Login และข้อมูลแยกตามผู้ใช้
- Frontend, notification และ public deployment

## 3. Technical Constraints

- Node.js + TypeScript + Express + SQLite
- ใช้ npm และ commit package-lock.json
- ใช้ Vitest + Supertest สำหรับ integration tests
- กรณี repository เดิม ยึดเวอร์ชันและรูปแบบที่มีอยู่
- กรณี repository ใหม่ เลือกเวอร์ชันที่เข้ากันได้และบันทึกใน
  package.json, lockfile และ README
- รัน local บน 127.0.0.1:3000
- SQLite ใช้ path จาก TASK_DB_PATH ค่าเริ่มต้น ./data/tasks.db
- สร้าง parent directory ของฐานข้อมูลได้เมื่อยังไม่มี
- tests ต้องใช้ฐานข้อมูลชั่วคราวแยกจากฐานข้อมูลผู้ใช้
- หากเริ่มต้นหรือเขียนฐานข้อมูลไม่ได้ ต้องรายงาน error
  และห้ามตอบ success โดยไม่ได้บันทึกจริง

## 4. Functional Requirements

| ID | Requirement |
| --- | --- |
| FR-001 | สร้างงานโดย default status เป็น todo |
| FR-002 | List งานพร้อม pagination |
| FR-003 | อ่านงานด้วย id |
| FR-004 | แก้ title, description และ status |
| FR-005 | ลบงานถาวร |
| FR-006 | ข้อมูลยังอยู่หลัง restart เมื่อใช้ DB path เดิม |

## 5. Data Model

Task:
- id: positive integer, สร้างโดยระบบ, ห้ามแก้
- title: string, trim ก่อนบันทึก, ยาว 1–200 Unicode code points
- description: string, ยาว 0–2000 Unicode code points
  default เป็น "", ไม่รับ null
- status: "todo" หรือ "done", default "todo"
- created_at: UTC timestamp ในรูปแบบ ISO 8601
- updated_at: UTC timestamp ในรูปแบบ ISO 8601

## 6. API Contract

Base path: /api/v1
Request/response เป็น JSON

| Method | Path | Success |
| --- | --- | --- |
| POST | /tasks | 201 |
| GET | /tasks | 200 |
| GET | /tasks/:id | 200 |
| PATCH | /tasks/:id | 200 |
| DELETE | /tasks/:id | 204, ไม่มี response body |

POST:
- required: title
- optional: description, status
- รับเฉพาะ fields ที่ระบุ; field เกินตอบ 422

PATCH:
- ส่งเฉพาะ field ที่ต้องการแก้
- ต้องมีอย่างน้อยหนึ่ง field ที่รองรับ
- validation เหมือน POST สำหรับ field ที่ส่ง
- id และ timestamps ห้ามแก้
- ส่งค่าเดิมซ้ำได้และตอบ 200

GET list:
- page default 1; per_page default 20
- page เป็น positive integer
- per_page เป็น integer 1–100
- query ที่รองรับมี page และ per_page เท่านั้น
- query ผิดรูปแบบ ค่าเกินช่วง หรือมีชื่ออื่น ตอบ 422
- เรียง created_at DESC และ id DESC เมื่อเวลาเท่ากัน
- เกินหน้าสุดท้าย: data เป็น [], total ยังเป็นจำนวนทั้งหมด

Successful single item response:
{"data":{"id":1,"title":"อ่านเอกสาร",
"description":"","status":"todo",
"created_at":"2026-10-17T14:00:00.000Z",
"updated_at":"2026-10-17T14:00:00.000Z"}}

Successful list response:
{"data":[],"meta":{"page":1,"per_page":20,"total":0}}

Errors:
- JSON syntax ผิด: 400 / INVALID_JSON
- body ไม่ใช่ JSON object: 422 / VALIDATION_ERROR
- POST/PATCH ไม่มี application/json: 415 / UNSUPPORTED_MEDIA_TYPE
- validation ไม่ผ่าน: 422 / VALIDATION_ERROR
- id ที่ไม่ใช่ positive integer: 400 / INVALID_ID
- id ถูกต้องแต่ไม่พบงาน: 404 / TASK_NOT_FOUND
- database error ระหว่าง request: 500 / INTERNAL_ERROR

Error shape:
{"error":{"code":"VALIDATION_ERROR",
"message":"Invalid request",
"details":{"title":["Required"]}}}

details เป็น object เสมอ; ถ้าไม่มีรายละเอียดใช้ {}
ข้อความ message ใช้สื่อสาร; tests ยึด code และรายละเอียด field
ห้ามตอบ stack trace หรือข้อมูลการเชื่อมต่อฐานข้อมูล

## 7. Quality Requirements

- ทุก query ที่มีค่าจากผู้ใช้ใช้ parameter binding
- production database path ต้องไม่ปะปนกับ test database
- ห้ามบันทึกความลับลง repository
- workshop นี้ไม่มี authentication และ bind เฉพาะ loopback
- ไม่กำหนด SLA หรือ throughput benchmark ในรอบนี้

## 8. Acceptance Criteria

AC-001 — FR-001:
POST ด้วย title ถูกต้อง ได้ 201, id และ default status=todo
GET ด้วย id เดิมได้ข้อมูลเดียวกัน

AC-002 — FR-001, FR-004:
title เป็นช่องว่างล้วน, title เกิน 200 code points,
status ผิดค่า และ unknown field ได้ 422 ตาม error shape

AC-003 — FR-002:
สร้าง 21 งาน; page=1&per_page=20 ได้ 20 งาน,
page=2 ได้ 1 งาน; total=21 และเรียงตาม contract

AC-004 — FR-003:
id=999 ที่ไม่มีอยู่ได้ 404 / TASK_NOT_FOUND
id=abc ได้ 400 / INVALID_ID

AC-005 — FR-004:
PATCH status เป็น done ได้ 200
GET ซ้ำยังได้ done; id และ created_at คงเดิม

AC-006 — FR-005:
DELETE งานที่มีอยู่ได้ 204 และ body ว่าง
GET งานที่ลบแล้วได้ 404

AC-007 — FR-006:
สร้างงาน ปิด server และเปิดใหม่โดยใช้ TASK_DB_PATH เดิม
GET แล้วพบงานเดิม

AC-008 — Contract errors:
JSON ผิด syntax ได้ 400 / INVALID_JSON
body เป็น array ได้ 422 / VALIDATION_ERROR
POST/PATCH ด้วย Content-Type: text/plain ได้ 415
page=0 และ per_page=101 ได้ 422

AC-009 — Database failure:
จำลอง database write ล้มเหลวใน test
POST ได้ 500 / INTERNAL_ERROR และไม่ส่ง stack trace

## 9. Verification Commands

Implementation ต้องสร้าง npm scripts ต่อไปนี้:
- npm run dev: เปิด development server
- npm run lint: ตรวจ lint
- npm test: รัน tests แบบจบครั้งเดียว
- npm run build: ตรวจ type และ build
- npm start: รัน built server

ต้องมี automated tests สำหรับ AC-001 ถึง AC-006,
AC-008 และ AC-009
AC-007 ใช้ automated restart test หรือคู่มือ manual ที่ทำซ้ำได้
README ต้องอธิบาย npm ci และแต่ละคำสั่ง
รายงานคำสั่งที่รัน ผล exit code และข้อจำกัดที่พบ

## 10. Delivery / Definition of Done

- CRUD และ persistence ทำงานตามสเปก
- automated tests, lint และ build ผ่าน
- มีหลักฐาน restart verification
- README มี setup, DB path และ curl examples
- ไม่มี feature เพิ่มนอก scope

## 11. Decisions

- Confirmed: single-user local workshop
- Confirmed: ทุกคนที่เข้าถึง process ถือเป็นผู้ใช้เดียวกัน
- Confirmed: data loss จาก DELETE เป็นพฤติกรรมตามขอบเขต
- Open questions: ไม่มีที่ขัดขวางการเริ่มงาน

ข้อสังเกต: คำสั่งในหัวข้อ Verification เป็น สิ่งที่ implementation ต้องจัดเตรียม ตัวอย่างนี้ยังไม่ได้สร้างแอปหรือยืนยันว่า test ผ่าน เมื่อใช้กับ repository ที่มีอยู่ให้แทนด้วยคำสั่งจริงที่ตรวจพบ

#6. เชื่อมสเปกกับ Codex

สร้าง AGENTS.md ที่ root ของ repository ตัวอย่างต่อไปนี้ใช้ร่วมกับ Task API ข้างต้น:

# Repository guidance

## Project context
- Read spec.md before implementing or changing product behavior.
- Treat spec.md as the agreed feature scope and acceptance criteria.
- Inspect existing code, package.json and lockfiles before proposing changes.
- If instructions or contracts conflict, report the conflict before changing
  the affected behavior.

## Working rules
- Keep changes within the requested scope.
- Preserve unrelated user changes.
- Reuse existing architecture and dependencies when practical.
- Do not rewrite acceptance criteria just to make failing code appear correct.
- Keep spec changes explicit when the user changes requirements.

## Verification
- For the Task API example, provide and run:
  npm run lint
  npm test
  npm run build
- Verify persistence using AC-007.
- Report actual results and distinguish checks that were not run.

ข้อความที่ให้เอเจนต์อ่าน spec.md เป็นคำแนะนำให้เปิดเอกสาร ไม่ใช่ระบบ import อัตโนมัติแบบ @path ของ Claude

หากใช้ Codex CLI ที่ติดตั้งและยืนยันตัวตนแล้ว ให้เปิดจาก directory ของโครงการ:

codex

จากนั้นส่ง prompt:

อ่าน AGENTS.md ที่เกี่ยวข้องและ spec.md
ตรวจ repository และสรุปความเข้าใจ ขอบเขต และประเด็นขัดแย้ง
ตอนนี้ยังไม่แก้ source code

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

หลังตรวจแผนแล้วจึงสั่ง:

ดำเนินงานตาม spec.md และ plan.md
เริ่ม milestone แรก: สร้างงานและอ่านงานให้จบครบเส้นทาง
รวม validation, persistence และ tests ที่เกี่ยวข้อง
รัน checks แล้วรายงาน requirement IDs ที่ทำเสร็จ
คำสั่งพร้อมผลจริง และสิ่งที่ยังไม่ผ่าน

สำหรับ Codex ผ่าน IDE ให้เปิด repository เดียวกันและใช้ prompt เดียวกัน โดยไม่ต้องพึ่งคำสั่ง CLI

#7. เชื่อมสเปกกับ Claude Code

ใช้ AGENTS.md ชุดเดียวกัน แล้วสร้าง CLAUDE.md ข้างไฟล์นั้น:

@AGENTS.md

## Claude Code workflow
- Read spec.md and the current plan.md before implementation.
- For substantial changes, inspect the relevant code and propose a plan first.
- Keep verification evidence tied to acceptance criteria.

@AGENTS.md ต้องอยู่เป็นข้อความจริงในไฟล์ CLAUDE.md ไม่ใช่อยู่ใน fenced code block ภายในไฟล์นั้น เพราะ syntax import ไม่ทำงานใน code fence [3]

ตัวอย่างนี้ import กติกาที่สั้น และสั่งอ่านสเปกตามงาน หากสเปกเล็กและต้องการรวมเข้า context โดยตรง จะเพิ่มบรรทัด @spec.md ใน CLAUDE.md ก็ได้ แต่เมื่อมีหลาย feature ควรโหลดเฉพาะเอกสารที่เกี่ยวข้อง

เปิด Claude Code ใน directory ของโครงการ:

claude

ส่ง prompt สำหรับเริ่มงาน:

อ่าน CLAUDE.md, AGENTS.md และ spec.md
ตรวจ repository ก่อนเสนอวิธีพัฒนา
สรุปเป้าหมาย ขอบเขต API contract และ acceptance criteria
ระบุช่องโหว่ของสเปกหรือข้อกำหนดที่ขัดแย้งกัน
ยังไม่แก้ source code

หากต้องการสำรวจโดยไม่แก้ไฟล์ ใช้ Plan Mode เช่น:

claude --permission-mode plan

ใน Plan Mode ให้ขอร่างแผนและตรวจข้อกำหนด เมื่อพร้อมพัฒนาให้ออกจาก Plan Mode ก่อน จากนั้นสั่งให้บันทึก plan.md และดำเนินงานตาม milestone [4]

บันทึกแผนที่ตกลงแล้วเป็น plan.md และดำเนินงาน milestone แรก
ตาม spec.md: สร้างงานและอ่านงาน
รวม validation, persistence และ tests ที่เกี่ยวข้อง
รัน checks แล้วรายงานหลักฐานตาม FR และ AC

การพิมพ์ว่า “ยังไม่แก้ source code” ใน prompt เป็นคำแนะนำเชิงพฤติกรรม ส่วน Plan Mode เป็นโหมดของเครื่องมือ เลือกใช้ให้ตรงกับช่วงงาน

#8. Prompt ให้ AI ช่วยสร้าง spec.md ตั้งแต่ต้น

ใช้ได้กับทั้งสองเครื่องมือ ปรับส่วนรายละเอียดโครงการก่อนส่ง:

ช่วยสร้าง spec.md สำหรับโครงการต่อไปนี้

ชื่อโครงการ: [ชื่อ]
ปัญหาและผู้ใช้: [รายละเอียด]
ความสามารถหลัก: [รายการ]
สิ่งที่ยังไม่ทำ: [รายการ]
ข้อจำกัดที่ยืนยันแล้ว: [รายละเอียด]
repository ปัจจุบัน: [มีหรือไม่มี]

ขั้นแรก:
1. ถ้ามี repository ให้อ่าน README, instruction files,
   manifests, lockfiles และ tests ที่เกี่ยวข้อง
2. แยกข้อเท็จจริงที่พบ ข้อเสนอใหม่ และสมมติฐาน
3. รวบรวมคำถามสำคัญเป็นชุดเดียว โดยถามเฉพาะเรื่องที่มีผล
   ต่อ scope, schema, security หรือ API contract
4. ถ้ายังไม่มีคำตอบ ให้ร่างส่วนที่ไม่ขึ้นกับคำตอบไว้ก่อน
   และทำเครื่องหมายประเด็นที่ยังเริ่ม implementation ไม่ได้

สร้างเฉพาะเอกสาร spec.md ในรอบนี้
ประกอบด้วย goal, scope, constraints, FR IDs, data model,
API/UI contract, errors, acceptance criteria, verification,
definition of done และ open questions
อย่าเริ่มเขียน source code
อย่าสมมติว่าคำสั่ง test หรือ dependency มีอยู่จริง

#9. Prompt สำหรับตรวจสเปกและตรวจงาน

#ตรวจสเปกก่อนพัฒนา

Review spec.md ในมุมผู้พัฒนาและผู้ทดสอบ
ตรวจความขัดแย้ง requirement ที่วัดผลไม่ได้
ขอบเขตที่ไม่ชัด missing errors และ AC ที่ไม่ครอบคลุม FR
จัดรายการตามผลกระทบ พร้อมเสนอข้อความแก้ไขที่เฉพาะเจาะจง
แยกคำถามที่ขัดขวาง implementation ออกจากเรื่องที่ตัดสินใจภายหลังได้
ยังไม่เปลี่ยนพฤติกรรมผลิตภัณฑ์

#ตรวจงานหลังพัฒนา

ตรวจ implementation เทียบกับ spec.md ฉบับปัจจุบัน
ตรวจโค้ดและรัน checks ที่เกี่ยวข้อง
สร้างตาราง FR/AC -> evidence -> pass/fail/not verified
แยกข้อผิดพลาดของ implementation ออกจากสเปกที่กำกวม
อย่าเปลี่ยนเกณฑ์ตรวจรับเพียงเพื่อให้โค้ดปัจจุบันผ่าน
รายงานคำสั่งที่รัน ผลลัพธ์ และข้อจำกัดจริง

ตัวอย่างตารางรายงาน — เป็นรูปแบบรายงานเท่านั้น ยังไม่มีผลทดสอบของแอปจริง:

#10. Checklist ก่อนส่งให้เอเจนต์พัฒนา

• [ ] อธิบายผู้ใช้ ปัญหา และผลลัพธ์ได้
• [ ] ขอบเขตชัด และไม่มี feature แอบเพิ่ม
• [ ] แยกข้อมูลจาก repository ออกจากข้อเสนอ
• [ ] เลือก stack และแหล่งอ้างอิงเวอร์ชันแล้ว
• [ ] มี requirement IDs
• [ ] ระบุ validation, errors และสิทธิ์เมื่อเกี่ยวข้อง
• [ ] แต่ละ requirement หลักมี acceptance criteria
• [ ] มีวิธีทดสอบที่ทำซ้ำได้
• [ ] แยกคำสั่งที่มีอยู่จริงจากคำสั่งที่ต้องสร้าง
• [ ] ไม่มี open question ที่ขัดขวาง milestone แรก
• [ ] ทั้ง Codex และ Claude Code อ้างอิง spec เดียวกัน
• [ ] เมื่อ scope เปลี่ยน อัปเดต spec, plan และ tests ที่เกี่ยวข้อง

#11. ข้อผิดพลาดที่พบบ่อย

#12. แหล่งอ้างอิง

เนื้อหาเชิงผลิตภัณฑ์อ้างอิงเอกสารทางการ ส่วนแม่แบบ Task API, checklist และ prompt เป็นตัวอย่างที่ผู้เขียนคู่มือนี้เสนอเพื่อการเรียนรู้

1. OpenAI — Iterating Development Workflows with Codex
   https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex
2. OpenAI — Custom instructions with AGENTS.md
   https://learn.chatgpt.com/docs/agent-configuration/agents-md
3. Anthropic — How Claude remembers your project
   https://code.claude.com/docs/en/memory
4. Anthropic — Best practices for Claude Code
   https://code.claude.com/docs/en/best-practices