# 3-플랫폼 워크플로우 자동화 동기화 — 설계 문서 - 작성일: 2026-06-04 - 상태: design (user-approved architecture, pending spec review) - 토픽: Claude Code의 워크플로우 자동화를 Codex CLI · Antigravity CLI로 공식문서 기반 동기화 --- ## 0. 문제 배경 이 저장소의 자동화는 **Claude Code 기준으로만 구체화**되어 있다. Codex CLI와 Antigravity CLI는 동일한 작업을 수행하지 못한다. 현재 격차 (감사 결과): | 항목 | Claude (`.claude/`) | Codex (`.codex/`) | Antigravity (`.agents/`) | |---|---|---|---| | agents | **9개** | 7개 (`branch-depth-auditor`·`coverage-auditor` 누락) | 7개 (동일 2개 누락) | | commands (13개) | ✅ | ❌ 전무 | ❌ 전무 | | hooks | `wiki_structure_lint.py` · `wiki_claim_gate.py` + settings | ❌ 전무 | `hooks.json` (hard-gate만) | | skills | `wiki-workflow/SKILL.md` | ❌ | `plugins/.../skills/wiki-workflow/SKILL.md` | 추가로 발견된 **기존 부채**: - Antigravity가 실제 로드하는 native registry `.agents/agents//agent.json` 이 **존재하지 않음** (SSOT `.md`만 있고 생성물 없음). - CLAUDE.md/README가 참조하는 변환 스크립트 `.agents/scripts/convert-wiki-agents.py` 가 **존재하지 않음**. - 즉 antigravity 포트는 "본문 .md만 있고 로딩 경로는 비어있는" 미완성 상태. 목표: **세 플랫폼이 동일한 작업을 수행**할 수 있도록, 각 플랫폼의 공식 메커니즘으로 commands·agents·hooks를 동기화한다. --- ## 1. 공식문서 기반 플랫폼 사실 (grounded) ### 1.1 Codex CLI (OpenAI, developers.openai.com/codex) - **Custom prompts**: `~/.codex/prompts/*.md` — **글로벌 홈 전용, repo 커밋 불가, deprecated**. - 근거: *"Custom prompts require explicit invocation and live in your local Codex home directory (for example, `~/.codex`), so they're not shared through your repository."* / *"Custom prompts are deprecated. Use skills for reusable instructions."* (developers.openai.com/codex/custom-prompts) - **Skills (commands의 정답 타깃)**: 디스커버리 경로에 `$REPO_ROOT/.agents/skills`, `$CWD/.agents/skills`, `$HOME/.agents/skills`, `/etc/codex/skills` 포함 → **`/.agents/skills//SKILL.md`** 가 repo 커밋·팀 공유 가능. - 호출: `/skills` picker 또는 `$name` 멘션(explicit) + description 의미 매칭(implicit). 인자는 prompt 자연어 + optional `scripts/`. - frontmatter: `name`(필수) + `description`(필수, "언제 발동/비발동"을 기술). (developers.openai.com/codex/skills) - **Native subagents**: `.codex/agents/*.toml` (project) + `~/.codex/agents/` (personal), 자동 디스커버리. 필수 필드 `name`·`description`·`developer_instructions`, 옵션 `model`·`sandbox_mode`·`mcp_servers`. `/agent`로 전환. → **현재 `.codex/agents/*.md` 수동 cat 방식을 대체.** (developers.openai.com/codex/subagents) - **Native hooks**: `/.codex/hooks.json` 또는 `config.toml`의 `[hooks]`. 이벤트: `PreToolUse`·`PermissionRequest`·`PostToolUse`·`PreCompact`·`PostCompact`·`UserPromptSubmit`·`SubagentStop`·`Stop`·`SessionStart`·`SubagentStart`. matcher(regex) + command handler 구조. (developers.openai.com/codex/hooks) - **Project instructions**: `AGENTS.md` (root-down 중첩·연결, 가까운 디렉토리가 override). `AGENTS.override.md` 우선. (developers.openai.com/codex/guides/agents-md) - **Sandbox / approval**: `sandbox_mode` = `read-only`/`workspace-write`/`danger-full-access`; project-local `config.toml`에서 hooks·MCP·agents·sandbox 설정 가능(profiles·notify·provider는 user-level 전용). ### 1.2 Antigravity CLI (Google, antigravity.google / Google Codelabs) - **Workflows (commands의 정답 타깃)**: `.agents/workflows/.md` (CLI plural) — Markdown, `/ ` slash 호출. *"By saving this text file inside `.agents/workflows/`, you are registering a brand new command directly into Antigravity's chat interface!"* (Google Codelabs: Autonomous AI Developer Pipelines). 글로벌은 `~/.gemini/antigravity/global_workflows/`. - **Subagents registry**: `.agents/agents//agent.json` (workspace) + `~/.gemini/antigravity-cli/agents//agent.json` (global). 스키마(실 디스크 검증): `config.customAgent.systemPromptSections[].content`(시스템 프롬프트 본문) · `toolNames[]`(per-agent allowlist) · `systemPromptConfig.includeSections[]` · `hidden: true`(dispatch-only). **`model:` 필드는 grounded 근거 없음 → 사용 금지.** - **Skills**: `.agents/skills//SKILL.md`, frontmatter `name`(옵션)+`description`(필수). **의미 기반 자동 트리거(slash 아님)** — slash가 필요하면 workflow를 써야 함. - **Hooks**: `.agents/hooks.json` (flat named format). 이벤트: `PreToolUse`·`PostToolUse`·`PreInvocation`·`PostInvocation`·`Stop`. **`Stop`은 응답 텍스트를 받지 못함** → content gate는 반드시 `PreToolUse`. matcher(glob `"*"`) + `hooks[]`(type `command`, `command`, `timeout`). - **Plugins**: `plugin.json`은 마커. **grounded 필드는 `name`뿐** → 확장 필드 사용 금지. workspace `.agents/plugins//`는 *authoring SSOT*이며 native 자동 로드 대상이 아님(생성된 `.agents/agents/`·`.agents/hooks.json`·`.agents/workflows/`를 CLI가 읽음). - **Tool 어휘** (`toolNames`): read/search = `view_file`·`find_by_name`·`grep_search`·`list_dir`·`read_url_content`·`search_web`; write = `write_to_file`·`replace_file_content`·`multi_replace_file_content`; exec/orchestration = `run_command`·`send_message`·`manage_task`·`schedule`. read-only agent은 write·`run_command` 제외. ### 1.3 결론 — 타깃 확정 | Claude 원본 | Codex 타깃 | Antigravity 타깃 | |---|---|---| | `.claude/commands/*.md` (13) | `.agents/skills//SKILL.md` (`$cmd`/`/skills`, repo 커밋) | `.agents/workflows/.md` (`/cmd` slash) | | `.claude/agents/*.md` (9) | `.codex/agents/*.toml` (native 자동등록, `sandbox_mode` 권한) | `.agents/agents//agent.json` (생성) | | `.claude/hooks/*.py` + settings | `.codex/hooks.json` | `.agents/hooks.json` (보강) | | `CLAUDE.md` | `AGENTS.md` (root) | CLAUDE.md authoritative 참조 유지 | > **주의**: `.agents/skills/`는 Codex와 Antigravity 양쪽이 읽는 공유 표면이다. Codex commands를 여기 두면 Antigravity도 이를 skill로 인식할 수 있다. 충돌을 피하려고 **Antigravity commands는 `.agents/workflows/`(slash 전용)로, Codex commands는 `.agents/skills/`(codex skill)로 분리** 한다. 동일 로직이지만 플랫폼별 호출 표면이 다르다. --- ## 2. 아키텍처 — SSOT→생성 사용자 결정: **생성 스크립트 방식** (repo의 기존 convert 모델과 일관). ``` SSOT (손으로 유지) 생성물 (스크립트가 기계 변환) ───────────────────── ────────────────────────────── .claude/commands/*.md ──┐ .claude/agents/*.md ─┼─► scripts/sync-automation.py ─► .codex/agents/*.toml .agents/plugins/.../*.md ─┘ .codex/hooks.json (정적) (Gemini hard-gate overlay) .agents/skills//SKILL.md .agents/workflows/.md .agents/agents//agent.json ``` ### 2.1 책임 분리 원칙 - **스크립트(기계적)**: frontmatter 변환, tool명 어휘 치환, 경로/호출 표면 적응, JSON/TOML 포장, 정합성 검증(생성물이 SSOT와 동기인지). - **손으로 유지(의미적)**: 플랫폼 고유 콘텐츠 — 특히 Antigravity agent의 **G1~G4 Gemini hard gate** 는 Claude/Codex SSOT에 없는 추가 본문이므로 *overlay로 합성*하며 생성하지 않는다. → antigravity agent는 Claude agent의 순수 파생이 아니라 "공통 본문 + gate overlay". ### 2.2 Agent SSOT 모델 (이중 SSOT 명시) - 공통 agent 본문: `.claude/agents/*.md` 가 canonical. - Antigravity는 hard-gate가 더 필요 → `.agents/plugins/wiki-superpowers/agents/*.md` 가 "공통 본문 + gate overlay"를 담는 antigravity SSOT로 계속 유지. 스크립트는 이 plugin `.md`에서 `agent.json`을 생성. - Codex `.codex/agents/*.toml`은 `.claude/agents/*.md`에서 생성(tool명 일반화 + `sandbox_mode` 매핑 + toml 포장). - read-only/​write 권한 정책은 agent별 메타로 스크립트가 보존: Codex는 `sandbox_mode`, Antigravity는 `toolNames` allowlist. --- ## 3. 생성 스크립트 설계 (`scripts/sync-automation.py`) 단일 진입점, 서브커맨드 또는 `--target` 으로 분기. 멱등(idempotent) — 같은 SSOT → 같은 출력. 변환 책임: 1. **agents → codex toml**: frontmatter(`name`/`description`) + 본문 → `developer_instructions`, tool 표현 일반화, 권한→`sandbox_mode`. 2. **agents → antigravity agent.json**: plugin `.md`(gate 포함) → `systemPromptSections[].content`, 권한→`toolNames` allowlist, read-only는 write/run_command 제외, `hidden:true` 정책 보존. 3. **commands → codex skill**: command `.md` → `.agents/skills//SKILL.md` (frontmatter `name`+`description`(언제 발동), 본문 tool명 일반화). 4. **commands → antigravity workflow**: command `.md` → `.agents/workflows/.md` (slash 호출 형식 + 인자 표기 + tool명 antigravity 어휘 치환). 5. **검증 모드(`--check`)**: 생성물이 SSOT와 동기인지 비교, drift 발견 시 비0 종료 → CI/hook 가능. per-agent / per-command 메타(권한 등급, antigravity tool allowlist)는 명시적 매핑 테이블로 스크립트 내부 또는 sidecar로 관리(파일명에서 추정 금지). --- ## 4. 단계 분할 (user-approved 순서: 엔진 → commands → hooks) ### Phase 0 — 생성 엔진 + agents (9개) - `scripts/sync-automation.py` 골격 작성 (agents 변환부). - 누락 2개 agent SSOT 추가: codex용 `.claude/agents/`에는 이미 존재 → codex `.toml`·antigravity plugin `.md`(gate 포함) 작성. - 생성: `.codex/agents/*.toml` ×9, `.agents/agents//agent.json` ×9. - **부수 효과**: antigravity 미완성 로딩 경로 복구 + codex 수동 cat → native toml 현대화. - 검증: `codex` 가 toml agent를 인식하는지(가능하면 실호출), `agent.json` 스키마가 실 디스크 예시와 일치하는지. ### Phase 1 — commands (13×2) - 생성: `.agents/skills//SKILL.md` ×13 (codex), `.agents/workflows/.md` ×13 (antigravity). - command별 frontmatter `description`을 "언제 발동/비발동" 기준으로 작성(codex implicit trigger 품질 좌우). - 검증: 대표 command(예: `/depth`, `/ingest`) 1~2개를 각 플랫폼에서 실제 호출해 동작 확인. ### Phase 2 — hooks + AGENTS.md + 문서 정리 - `.codex/hooks.json` 작성: `wiki_structure_lint.py`·`wiki_claim_gate.py`를 `PreToolUse`(Edit|Write matcher)로 연결. hook 스크립트는 공유(top-level 위치 검토). - `.agents/hooks.json` 보강: structure-lint/claim-gate 반영(단 content gate는 `PreToolUse`만). - `AGENTS.md`(root) 작성: CLAUDE.md 운영규칙의 codex판(또는 얇은 포인터). - CLAUDE.md·`.codex/agents/README.md`·antigravity README 갱신: 구식 "수동 cat" 서술 제거, native toml/workflow/skills 경로 반영, 변환 스크립트 사용법 문서화. 각 Phase는 독립 커밋 + 검증 게이트. Phase 0 완료 후 사용자 확인 → Phase 1 진행. --- ## 5. 범위 밖 (YAGNI) - 코드 작업용 agent(ca-tmpl `ca-implementer` 등)는 본 vault 범위 밖 — 손대지 않음. - 글로벌 설치(`~/.codex`, `~/.gemini/antigravity-cli/`) 자동화 제외 — repo 커밋 산출물만 생성. - `rules/`·`templates/`는 이미 3 플랫폼 공유 — 변경 없음. - Codex custom prompts(`~/.codex/prompts/`) — deprecated·글로벌 전용이라 사용 안 함. - per-agent `model:` 지정(antigravity) — grounded 필드 없음, 미사용. - `plugin.json` 확장 필드 — `name`만 grounded, 미사용. --- ## 6. 리스크 / 미해결 - **기계 변환의 fidelity 한계**: Claude command 본문의 Claude-idiom 서술은 완벽히 idiomatic하게 변환되지 않음. 사용자가 생성 방식을 선택하며 수용한 trade-off. 대표 command 실호출로 "동작은 동등"함을 검증해 완화. - **`.agents/skills/` 공유 표면 충돌**: Codex skill과 Antigravity가 같은 디렉토리를 읽음. commands는 antigravity는 workflow로 분리하므로 직접 충돌은 회피하나, 기존 `wiki-workflow` skill 위치(`.agents/plugins/.../skills/` vs `.agents/skills/`)의 정합성은 Phase 1에서 점검 필요. - **antigravity `agent.json` 스키마 미공개**: 공식 스키마가 아닌 실 디스크 관측 기반. 스키마 변동 시 변환부 수정 필요. `--check` 모드로 조기 탐지. - **codex skill 인자 모델**: 구조적 `$ARGUMENTS`는 legacy prompts 기능이고 skill은 자연어 인자 → 일부 command의 인자 전달 UX가 Claude와 다를 수 있음. 대표 검증에서 확인. --- ## 7. 검증 접근 - Phase별 "대표 산출물 실호출" 게이트(스모크): toml agent 1개, workflow 1개, skill 1개를 실제 CLI에서 호출. - `sync-automation.py --check` 로 SSOT↔생성물 drift 0 확인. - antigravity `agent.json` 은 실 디스크 예시 스키마와 키 단위 대조. - 최종 감사표(§0)의 9/13/hooks/skills 모든 칸이 세 플랫폼에서 채워졌는지 재확인.