Prepare Claude Code + Codex CLI Compatibility

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 ก่อน:

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

ตรวจสอบ:

.agents/skills/
~/.agents/skills/

รวมถึง:

• project skills
• user skills
• skill discovery
• SKILL.md specification
• frontmatter ที่จำเป็น
• legacy/deprecated paths
• compatibility กับ symlink

ตรวจสอบด้วยว่า path หรือ convention รุ่นเก่า เช่น:

.codex/skills/

ยังรองรับอยู่หรือถูก deprecate แล้ว

Custom Agents

ตรวจสอบ specification ล่าสุดของ:

.codex/agents/*.toml
~/.codex/agents/*.toml

รวมถึง fields ที่รองรับ เช่น:

name
description
developer_instructions

ห้าม assume schema จาก prompt นี้ หาก documentation ปัจจุบันเปลี่ยนไป

Commands / Prompts

ตรวจสอบสถานะล่าสุดของ:

~/.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:

CLAUDE.md
AGENTS.md
AGENTS.override.md

.claude/
  agents/
  skills/
  commands/

.agents/
  skills/

.codex/
  agents/
  skills/

.mcp.json
.gitignore

ตรวจสอบด้วยว่า .gitignore หรือ global gitignore มี rule ที่กระทบ:

.claude/
.agents/
.codex/
AGENTS.md
CLAUDE.md

จากนั้นตรวจสอบ User-level configuration:

~/.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 ที่มี:

CLAUDE.md

แต่ยังไม่มี:

AGENTS.md

ให้สร้าง:

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 เช่น:

<!-- BEGIN generated: claude-codex-sync -->
...
<!-- END generated: claude-codex-sync -->

เพื่อให้ update ซ้ำได้โดยไม่ duplicate

---

Phase 3 — Skills

Claude Skills ยังคงเป็น source of truth:

.claude/skills/
~/.claude/skills/

Codex compatibility layer ใช้ path ที่ documentation ปัจจุบันกำหนด

หาก path ปัจจุบันยังเป็น:

.agents/skills/
~/.agents/skills/

ให้สร้าง symlink ราย skill

ตัวอย่าง project-level:

.agents/skills/<skill-name>
    -> ../../.claude/skills/<skill-name>

User-level:

~/.agents/skills/<skill-name>
    -> ~/.claude/skills/<skill-name>

แต่ต้องคำนวณ relative path จาก filesystem จริง ห้าม hardcode path หากโครงสร้างไม่ตรงตัวอย่าง

Collision Rule

หาก destination:

.agents/skills/<skill-name>

มีอยู่แล้ว:

• ถ้าเป็น symlink ที่ถูกต้อง → skip
• ถ้าเป็น broken symlink → report
• ถ้าเป็น symlink ไปที่อื่น → report conflict
• ถ้าเป็น directory/file จริง → preserve และ skip
• ห้าม overwrite อัตโนมัติ

---

Phase 4 — Claude Commands → Codex Skills

สำหรับ:

.claude/commands/*.md
~/.claude/commands/*.md

สร้าง Codex-compatible Skill ตาม specification ปัจจุบัน

เช่น:

.agents/skills/<command-name>/SKILL.md

หรือ user-level equivalent

ใช้ชื่อ command เดิมโดยตรง

ไม่ต้องเพิ่ม prefix ที่อ้างถึงระบบต้นทาง

เช่น:

.claude/commands/review.md

กลายเป็น:

.agents/skills/review/SKILL.md

ไม่ใช่:

source-command-review
claude-review

Generated Skill

ต้องมี metadata/frontmatter ตาม specification ล่าสุดของ Codex

อย่างน้อย หาก schema ปัจจุบันรองรับ:

---
name: review
description: ...
---

รักษา intent ของ command เดิมให้มากที่สุด

ถ้ามี syntax เฉพาะ Claude เช่น:

$ARGUMENTS

ให้แปลงเป็นคำอธิบายเชิง semantic สำหรับ Codex

อย่า copy syntax ที่ Codex ไม่เข้าใจแบบตรง ๆ

ทุก generated skill ต้องมี marker ระบุ source เช่น:

Generated from: .claude/commands/review.md
Managed by: claude-codex compatibility sync

เพื่อรองรับ regeneration

---

Phase 5 — Claude Agents → Codex Agents

สำหรับ:

.claude/agents/*.md
~/.claude/agents/*.md

สร้าง Codex agent ตาม schema ปัจจุบัน เช่น:

.codex/agents/<agent-name>.toml

รักษา:

• agent purpose
• role
• behavior
• workflow
• constraints
• tool expectations

หาก Claude agent มี:

model:

ห้ามนำชื่อ Claude model ไปใช้กับ Codex โดยตรง

ให้ omit field นี้ เว้นแต่ Codex documentation ปัจจุบันมี migration mapping ที่ชัดเจน

หากมี:

tools:

และไม่มี mapping แบบ 1:1

ให้ preserve ความหมายไว้ใน:

developer_instructions

แทนการสร้าง tool configuration ที่อาจผิด

ทุก generated agent ต้องระบุ source file เพื่อรองรับ regeneration

---

Phase 6 — User-Level Codex Instructions

สร้างหรือปรับ:

~/.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

อ่าน:

~/.codex/config.toml

ก่อนแก้ทุกครั้ง

ห้ามสร้าง config ใหม่ทับของเดิม

รักษา configuration เดิมทั้งหมด เช่น:

• notify
• projects
• plugins
• MCP servers
• model configuration
• trust settings
• feature flags
• custom settings อื่น ๆ

หาก documentation ปัจจุบันรองรับ:

project_doc_fallback_filenames = ["CLAUDE.md"]

ให้ merge เข้า config

จากนั้นหา CLAUDE.md ที่ใหญ่ที่สุดใน workspace

คำนวณขนาดจริงเป็น bytes และตั้ง:

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 โดยใช้ชื่อที่เป็นกลางและไม่ผูกกับชื่อบุคคล เช่น:

~/.claude/skills/claude-codex-sync/

หรือชื่อ generic ที่เหมาะสมตาม convention ที่พบใน environment

ภายในควรมี:

SKILL.md
scripts/

รองรับอย่างน้อย:

--user
--project <path>
--all-workspace <root>
--dry-run

ควรมี:

--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 เช่น:

generated-by: claude-codex-sync
source: <source-path>

อย่าใช้ชื่อบุคคล ชื่อ 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:

ตรวจสอบ:

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 อีกครั้ง

git diff --cached

ถ้าพบ:

• token
• API key
• credential
• private key
• .env secret
• suspicious credential material

หยุดทันที

ห้าม commit

Commit Scope

แต่ละ project ให้ commit เฉพาะ compatibility artifacts ที่สร้างหรือแก้โดยงานนี้ เช่น:

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

ตรวจสอบ:

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

ตรวจ:

git status
git diff
git log -1

Codex

เปิด Codex จาก project directory และทดสอบ instruction discovery

ใช้ prompt:

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

ให้คำสั่งสำหรับตรวจสอบภายหลัง รวมถึง:

codex --version

และการเปิด Codex ใน project แล้วสั่ง:

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