# Mission: Prepare Claude Code + Codex CLI Compatibility เตรียม workspace นี้ให้สามารถใช้งาน **Claude Code และ Codex CLI ร่วมกันได้อย่างเป็นระบบในทุกโปรเจกต์** หลักการสำคัญ: - **Claude Code = Source of Truth** - **Codex CLI = Consumer / Compatibility Layer** - หลีกเลี่ยงการ duplicate configuration ที่อาจ diverge ในอนาคต - ใช้ **symlink / generated compatibility files** เมื่อเหมาะสม - ทุกสิ่งที่ generate ต้อง **ตรวจสอบย้อนกลับได้, รันซ้ำได้ และ idempotent** - ห้ามทำลาย configuration เดิมของ Claude Code หรือ Codex - รองรับทั้ง **User-level** และ **Project-level configuration** > ข้อมูลเกี่ยวกับ Codex ใน prompt นี้ถือเป็น baseline เท่านั้น > หาก documentation หรือ CLI เวอร์ชันปัจจุบันขัดกับ prompt ให้ **official OpenAI documentation / repository / CLI ปัจจุบันเป็น source of truth** และรายงานความแตกต่างก่อนดำเนินการ --- # Phase 0 — Research Before Changes **ห้ามแก้ไขไฟล์ใด ๆ ก่อนจบ phase นี้** ตรวจสอบ environment ก่อน: ```bash codex --version claude --version git --version ``` จากนั้นค้นข้อมูลล่าสุดจากแหล่งข้อมูลทางการของ OpenAI เกี่ยวกับ Codex CLI โดยเฉพาะ: ## Instruction discovery ตรวจสอบพฤติกรรมล่าสุดของ: - `~/.codex/AGENTS.md` - `AGENTS.override.md` - `AGENTS.md` - instruction discovery / precedence - `project_doc_fallback_filenames` - `project_doc_max_bytes` - default values และข้อจำกัดปัจจุบัน อย่าสมมุติว่า precedence หรือ default values ที่เขียนใน prompt นี้ยังถูกต้อง ## Skills ตรวจสอบ: ```text .agents/skills/ ~/.agents/skills/ ``` รวมถึง: - project skills - user skills - skill discovery - `SKILL.md` specification - frontmatter ที่จำเป็น - legacy/deprecated paths - compatibility กับ symlink ตรวจสอบด้วยว่า path หรือ convention รุ่นเก่า เช่น: ```text .codex/skills/ ``` ยังรองรับอยู่หรือถูก deprecate แล้ว ## Custom Agents ตรวจสอบ specification ล่าสุดของ: ```text .codex/agents/*.toml ~/.codex/agents/*.toml ``` รวมถึง fields ที่รองรับ เช่น: ```text name description developer_instructions ``` ห้าม assume schema จาก prompt นี้ หาก documentation ปัจจุบันเปลี่ยนไป ## Commands / Prompts ตรวจสอบสถานะล่าสุดของ: ```text ~/.codex/prompts/ ``` และวิธีที่ OpenAI แนะนำให้ migrate reusable prompts / commands ไปเป็น Skills ## Official migration guidance ค้นหา migration guide / skill / documentation ทางการของ OpenAI สำหรับการย้าย configuration จาก Claude Code หรือ agent ecosystem อื่นมายัง Codex หากพบ migration skill หรือ repository ทางการ ให้ศึกษา: - migration strategy - differences - unsupported features - behavioral differences - recommended compatibility patterns ก่อนออกแบบ migration ของ workspace นี้ ## Research Output ก่อนลงมือ ให้สรุป: | Topic | Current Behavior | Source | Impact | |---|---|---|---| | Instruction discovery | | | | | Skills | | | | | Agents | | | | | Commands / Prompts | | | | | Config | | | | | Migration guidance | | | | แยกให้ชัดว่าอะไรคือ: - Verified current behavior - Deprecated / legacy behavior - Assumption ที่ยัง verify ไม่ได้ - สิ่งที่แตกต่างจาก prompt นี้ จากนั้นจึงเข้าสู่ Phase 1 --- # Phase 1 — Audit Workspace สำรวจ workspace root และค้นหา **ทุก Git project / project directory ที่เกี่ยวข้อง** ตรวจสอบ Project-level: ```text CLAUDE.md AGENTS.md AGENTS.override.md .claude/ agents/ skills/ commands/ .agents/ skills/ .codex/ agents/ skills/ .mcp.json .gitignore ``` ตรวจสอบด้วยว่า `.gitignore` หรือ global gitignore มี rule ที่กระทบ: ```text .claude/ .agents/ .codex/ AGENTS.md CLAUDE.md ``` จากนั้นตรวจสอบ User-level configuration: ```text ~/.claude/ ~/.claude/agents/ ~/.claude/skills/ ~/.claude/commands/ ~/.codex/ ~/.codex/AGENTS.md ~/.codex/config.toml ~/.codex/agents/ ~/.agents/ ~/.agents/skills/ ``` รวมถึง: - Claude hooks - Claude settings - MCP configuration - Codex configuration ที่มีอยู่ - symlink ที่มีอยู่แล้ว ## Audit Safety ใน phase นี้: **Read-only เท่านั้น** ห้าม: - create - overwrite - delete - move - commit - push ## Audit Report แสดงตารางอย่างน้อย: | Project | CLAUDE.md | AGENTS.md | Claude Agents | Claude Skills | Commands | Codex Existing | MCP | Gitignore Issues | |---|---:|---:|---:|---:|---:|---:|---:|---:| พร้อมสรุป User-level configuration แยกอีกส่วน --- # Phase 2 — Compatibility Architecture ใช้หลักการต่อไปนี้เป็น default decision **ไม่ต้องถามซ้ำ** เว้นแต่พบ conflict ที่อาจทำข้อมูลสูญหาย ## 2.1 Project Instructions สำหรับ project ที่มี: ```text CLAUDE.md ``` แต่ยังไม่มี: ```text AGENTS.md ``` ให้สร้าง: ```text AGENTS.md -> CLAUDE.md ``` เป็น **relative symlink** เป้าหมายคือ: > One source, two entry points. Claude Code อ่าน `CLAUDE.md` Codex อ่าน `AGENTS.md` แต่เป็นเนื้อหาเดียวกันจริง ๆ ### Existing AGENTS.md ถ้า `AGENTS.md` มีอยู่แล้ว: **ห้าม overwrite** ตรวจสอบก่อนว่าเป็น: 1. symlink ไป `CLAUDE.md` อยู่แล้ว 2. symlink ไปที่อื่น 3. regular file 4. generated compatibility file 5. user-maintained Codex-specific instructions หากเป็น regular file หรือมีเนื้อหาที่มนุษย์เขียน: ให้ preserve เนื้อหาเดิม และเลือก compatibility strategy ที่ไม่ทำข้อมูลสูญหาย หากสามารถใช้ include/reference mechanism ตามมาตรฐานปัจจุบันได้ ให้ใช้วิธีมาตรฐานนั้น หากไม่ได้ ให้เพิ่ม generated compatibility block ที่ชี้ให้ Codex ใช้ `CLAUDE.md` ต้องมี marker เช่น: ```text ... ``` เพื่อให้ update ซ้ำได้โดยไม่ duplicate --- # Phase 3 — Skills Claude Skills ยังคงเป็น source of truth: ```text .claude/skills/ ~/.claude/skills/ ``` Codex compatibility layer ใช้ path ที่ documentation ปัจจุบันกำหนด หาก path ปัจจุบันยังเป็น: ```text .agents/skills/ ~/.agents/skills/ ``` ให้สร้าง symlink ราย skill ตัวอย่าง project-level: ```text .agents/skills/ -> ../../.claude/skills/ ``` User-level: ```text ~/.agents/skills/ -> ~/.claude/skills/ ``` แต่ต้องคำนวณ relative path จาก filesystem จริง ห้าม hardcode path หากโครงสร้างไม่ตรงตัวอย่าง ## Collision Rule หาก destination: ```text .agents/skills/ ``` มีอยู่แล้ว: - ถ้าเป็น symlink ที่ถูกต้อง → skip - ถ้าเป็น broken symlink → report - ถ้าเป็น symlink ไปที่อื่น → report conflict - ถ้าเป็น directory/file จริง → preserve และ skip - ห้าม overwrite อัตโนมัติ --- # Phase 4 — Claude Commands → Codex Skills สำหรับ: ```text .claude/commands/*.md ~/.claude/commands/*.md ``` สร้าง Codex-compatible Skill ตาม specification ปัจจุบัน เช่น: ```text .agents/skills//SKILL.md ``` หรือ user-level equivalent ใช้ชื่อ command เดิมโดยตรง **ไม่ต้องเพิ่ม prefix ที่อ้างถึงระบบต้นทาง** เช่น: ```text .claude/commands/review.md ``` กลายเป็น: ```text .agents/skills/review/SKILL.md ``` ไม่ใช่: ```text source-command-review claude-review ``` ## Generated Skill ต้องมี metadata/frontmatter ตาม specification ล่าสุดของ Codex อย่างน้อย หาก schema ปัจจุบันรองรับ: ```yaml --- name: review description: ... --- ``` รักษา intent ของ command เดิมให้มากที่สุด ถ้ามี syntax เฉพาะ Claude เช่น: ```text $ARGUMENTS ``` ให้แปลงเป็นคำอธิบายเชิง semantic สำหรับ Codex อย่า copy syntax ที่ Codex ไม่เข้าใจแบบตรง ๆ ทุก generated skill ต้องมี marker ระบุ source เช่น: ```text Generated from: .claude/commands/review.md Managed by: claude-codex compatibility sync ``` เพื่อรองรับ regeneration --- # Phase 5 — Claude Agents → Codex Agents สำหรับ: ```text .claude/agents/*.md ~/.claude/agents/*.md ``` สร้าง Codex agent ตาม schema ปัจจุบัน เช่น: ```text .codex/agents/.toml ``` รักษา: - agent purpose - role - behavior - workflow - constraints - tool expectations หาก Claude agent มี: ```text model: ``` ห้ามนำชื่อ Claude model ไปใช้กับ Codex โดยตรง ให้ omit field นี้ เว้นแต่ Codex documentation ปัจจุบันมี migration mapping ที่ชัดเจน หากมี: ```text tools: ``` และไม่มี mapping แบบ 1:1 ให้ preserve ความหมายไว้ใน: ```text developer_instructions ``` แทนการสร้าง tool configuration ที่อาจผิด ทุก generated agent ต้องระบุ source file เพื่อรองรับ regeneration --- # Phase 6 — User-Level Codex Instructions สร้างหรือปรับ: ```text ~/.codex/AGENTS.md ``` ให้เป็น **Codex-specific global instructions** อย่า symlink global file นี้กับ Claude โดยอัตโนมัติ เพราะสองระบบอาจต้องการ bootstrap instructions ต่างกัน อ่าน global/user-level Claude instructions ที่มีอยู่จริงก่อน แล้วนำเฉพาะ behavior ที่ควรใช้ร่วมกันมา adapt ตัวอย่างสิ่งที่ควรพิจารณา: - user preferences - preferred language - communication style - repository workflow - Git rules - secret scanning - file-placement rules - safety constraints - coding conventions จากนั้นเพิ่ม section: # Claude Code → Codex Compatibility อธิบาย mapping ที่จำเป็น เช่น: | Claude Concept | Codex Equivalent | |---|---| | `CLAUDE.md` | `AGENTS.md` compatibility entry | | Claude Skill | Codex Skill | | Slash Command | Skill | | Claude Agent/Subagent | Codex Agent | | Claude-specific interaction | Native Codex interaction | หาก Claude มี tool หรือ feature ที่ Codex ไม่มี equivalent: **ห้าม pretend ว่ามี** ให้ระบุ fallback behavior ที่เหมาะสม --- # Phase 7 — Codex Config อ่าน: ```text ~/.codex/config.toml ``` ก่อนแก้ทุกครั้ง **ห้ามสร้าง config ใหม่ทับของเดิม** รักษา configuration เดิมทั้งหมด เช่น: - notify - projects - plugins - MCP servers - model configuration - trust settings - feature flags - custom settings อื่น ๆ หาก documentation ปัจจุบันรองรับ: ```toml project_doc_fallback_filenames = ["CLAUDE.md"] ``` ให้ merge เข้า config จากนั้นหา `CLAUDE.md` ที่ใหญ่ที่สุดใน workspace คำนวณขนาดจริงเป็น bytes และตั้ง: ```text project_doc_max_bytes ``` ให้เพียงพอ ควรมี headroom ที่สมเหตุสมผลเพื่อรองรับการเพิ่ม instruction ในอนาคต ห้ามลดค่าปัจจุบันหากค่าปัจจุบันสูงกว่า requirement ก่อนเขียนกลับ: - validate TOML - preserve unrelated configuration - ทำ backup หาก parser/write strategy มีความเสี่ยงต่อ formatting หรือ comments --- # Phase 8 — Build a Reusable Sync Tool ห้ามทำ migration แบบ manual อย่างเดียว สร้าง reusable synchronization skill/tool ใน **Claude user-level skills directory** โดยใช้ชื่อที่เป็นกลางและไม่ผูกกับชื่อบุคคล เช่น: ```text ~/.claude/skills/claude-codex-sync/ ``` หรือชื่อ generic ที่เหมาะสมตาม convention ที่พบใน environment ภายในควรมี: ```text SKILL.md scripts/ ``` รองรับอย่างน้อย: ```bash --user --project --all-workspace --dry-run ``` ควรมี: ```bash --help ``` ด้วย ## Required Properties sync tool ต้อง: - idempotent - safe to rerun - preserve user files - detect conflicts - detect broken symlinks - use relative symlinks สำหรับ project-level เมื่อเหมาะสม - support paths ที่มี spaces - handle missing directories - avoid duplicate generated blocks - update generated files เมื่อ source เปลี่ยน - ไม่ delete user-created files - return non-zero exit code เมื่อเกิด critical failure - มี dry-run ที่ไม่ mutate filesystem จริง ถ้าจำเป็นต้องใช้ marker ให้ใช้ marker แบบ generic เช่น: ```text generated-by: claude-codex-sync source: ``` อย่าใช้ชื่อบุคคล ชื่อ workspace หรือชื่อโปรเจกต์เฉพาะเจาะจงใน architecture --- # Phase 9 — Run the Sync หลังสร้างและทดสอบ sync tool แล้ว: 1. Run `--dry-run` 2. ตรวจสอบ output 3. Run user-level sync 4. Run ทุก project ใน workspace 5. Run `--dry-run` ซ้ำอีกครั้ง dry-run รอบสุดท้ายควรแสดงว่า: > ไม่มี unintended changes เหลืออยู่ หาก run ครั้งที่สองสร้าง duplicate หรือเปลี่ยนไฟล์โดยไม่มีเหตุผล: ถือว่า **idempotency test failed** ให้แก้ sync tool ก่อนดำเนินการต่อ --- # Phase 10 — Hooks & MCP สำหรับ: - Claude hooks - `.mcp.json` - Claude MCP configuration - Codex MCP configuration **ยังไม่ migrate อัตโนมัติ** ให้ audit และรายงานเท่านั้น เหตุผล: configuration และ execution semantics อาจไม่เทียบกันแบบ 1:1 แสดงเป็น: | Source | Feature | Codex Equivalent | Status | Recommended Action | |---|---|---|---|---| --- # Phase 11 — Git Safety ก่อนทำ Git operation: ตรวจสอบ: ```bash git status git branch --show-current git remote -v ``` ห้าม: - force push - rewrite history - reset unrelated work - stash/delete user work โดยพลการ - commit unrelated files ## Secret Check ก่อน `git add`: ทำ secret/sensitive-data check รอบแรกกับไฟล์ที่จะเพิ่ม หลัง staging: ตรวจสอบ staged diff และ secret อีกครั้ง ```bash git diff --cached ``` ถ้าพบ: - token - API key - credential - private key - `.env` secret - suspicious credential material **หยุดทันที** ห้าม commit ## Commit Scope แต่ละ project ให้ commit เฉพาะ compatibility artifacts ที่สร้างหรือแก้โดยงานนี้ เช่น: ```text AGENTS.md .agents/ .codex/ ``` รวมถึงไฟล์อื่นเฉพาะเมื่อจำเป็นต่อ compatibility architecture และต้องระบุเหตุผลในรายงาน ใช้ branch ปัจจุบัน ห้ามสร้าง branch ใหม่เว้นแต่จำเป็นจริง ๆ จากนั้น push ไป remote/branch เดิม หาก push fail: **หยุด project นั้นและรายงาน** ห้าม: - force push - rebase อัตโนมัติ - pull --rebase - merge remote changes - เปลี่ยน branch เพื่อแก้ปัญหาเอง --- # Phase 12 — Verification หลัง migration ให้ verify อย่างน้อย: ## Filesystem ตรวจสอบ: ```text AGENTS.md → CLAUDE.md Claude Skills → Codex Skills Claude Commands → generated Codex Skills Claude Agents → Codex Agents ``` ตรวจ broken symlinks ## Idempotency รัน sync ซ้ำแบบ dry-run ต้องไม่มี unexpected mutation ## Git ตรวจ: ```bash git status git diff git log -1 ``` ## Codex เปิด Codex จาก project directory และทดสอบ instruction discovery ใช้ prompt: ```text Summarize the instructions currently governing this project. Include the instruction files and compatibility layers you discovered. ``` ตรวจว่า Codex: - เห็น project instructions - เห็น global instructions - discover skills ได้ - discover agents ได้ตาม capability ปัจจุบัน --- # Phase 13 — Final Report สรุปเป็นตาราง: | Project | Instructions | Skills | Commands | Agents | Git | Push | Verification | Notes | |---|---|---|---|---|---|---|---|---| จากนั้นแสดง: ## User-level Changes ระบุ: - `~/.codex/AGENTS.md` - `~/.codex/config.toml` - user skills - user agents - sync tool ## Conflicts / Skipped Items รายการทุกไฟล์ที่: - มีของเดิม - ไม่ได้ overwrite - conflict - broken symlink - unsupported - ต้องให้มนุษย์ตัดสินใจ ## Pending Migration อย่างน้อยตรวจสอบ: - hooks - MCP - legacy Codex skill directories - ignored `.claude/` - unsupported Claude-specific features - existing Codex-native configuration ที่ไม่ได้ merge เพราะ conflict ## Verification Commands ให้คำสั่งสำหรับตรวจสอบภายหลัง รวมถึง: ```bash codex --version ``` และการเปิด Codex ใน project แล้วสั่ง: ```text Summarize the instructions currently governing this project. ``` --- # Non-Negotiable Safety Rules 1. **Claude configuration คือ source of truth** 2. ห้ามแก้ `.claude/` หรือ `~/.claude/` ยกเว้นการสร้าง sync tool ตามงานนี้ 3. ห้าม overwrite user-maintained Codex files 4. ห้าม delete configuration เพื่อแก้ conflict 5. Existing file → inspect before modify 6. Existing symlink → resolve before modify 7. Generated artifact ทุกชิ้นต้อง trace กลับ source ได้ 8. ทุก operation ต้องออกแบบให้ rerun ได้ 9. Documentation ปัจจุบันสำคัญกว่า assumption ใน prompt 10. Unsupported feature ต้องรายงานตรง ๆ ห้ามสร้าง compatibility ปลอม 11. Git commit ต้อง scoped เฉพาะงานนี้ 12. ห้าม force push 13. Secret check ก่อน staging และก่อน commit 14. หาก operation มีโอกาสทำข้อมูลสูญหายและไม่มี rule รองรับ → **หยุดเฉพาะส่วนนั้นและรายงาน แทนการเดา** 15. อย่าถามคำถามที่สามารถ resolve ได้จาก filesystem, Git state, CLI help หรือ official documentation 16. ทำงานต่อให้ครบทุกส่วนที่ปลอดภัย แม้บาง project จะมี conflict # Definition of Done งานถือว่าเสร็จเมื่อ: - Claude Code ยังคงทำงานจาก configuration เดิม - Codex สามารถ consume project instructions ได้ - Skills ที่ compatible ถูก discover จาก Codex - Commands ที่เหมาะสมถูกแปลงเป็น Skills - Agents ที่เหมาะสมถูกแปลงเป็น Codex Agents - User-level compatibility ถูกติดตั้ง - มี reusable sync tool - sync tool ผ่าน dry-run + idempotency test - ไม่มี source configuration ถูกทำลาย - ไม่มี secret ถูก commit - แต่ละ project ถูก commit/push ตามกฎที่กำหนด หรือมีเหตุผลชัดเจนว่าทำไมไม่ได้ - conflicts และ unsupported features ถูกบันทึกครบ - final report แสดงสถานะของทุก project