donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/docs/superpowers/specs/2026-06-04-three-platform-workflow-sync-design.md
T

13 KiB
Raw Permalink Blame History

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/<name>/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 포함 → <repo>/.agents/skills/<name>/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: <repo>/.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/<name>.md (CLI plural) — Markdown, /<name> <args> 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/<name>/agent.json (workspace) + ~/.gemini/antigravity-cli/agents/<name>/agent.json (global). 스키마(실 디스크 검증): config.customAgent.systemPromptSections[].content(시스템 프롬프트 본문) · toolNames[](per-agent allowlist) · systemPromptConfig.includeSections[] · hidden: true(dispatch-only). model: 필드는 grounded 근거 없음 → 사용 금지.
  • Skills: .agents/skills/<name>/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/<name>/는 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/<cmd>/SKILL.md ($cmd//skills, repo 커밋) .agents/workflows/<cmd>.md (/cmd slash)
.claude/agents/*.md (9) .codex/agents/*.toml (native 자동등록, sandbox_mode 권한) .agents/agents/<name>/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/<cmd>/SKILL.md
                                                               .agents/workflows/<cmd>.md
                                                               .agents/agents/<name>/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/<cmd>/SKILL.md (frontmatter name+description(언제 발동), 본문 tool명 일반화).
  4. commands → antigravity workflow: command .md → .agents/workflows/<cmd>.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/<name>/agent.json ×9.
  • 부수 효과: antigravity 미완성 로딩 경로 복구 + codex 수동 cat → native toml 현대화.
  • 검증: codex 가 toml agent를 인식하는지(가능하면 실호출), agent.json 스키마가 실 디스크 예시와 일치하는지.

Phase 1 — commands (13×2)

  • 생성: .agents/skills/<cmd>/SKILL.md ×13 (codex), .agents/workflows/<cmd>.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 모든 칸이 세 플랫폼에서 채워졌는지 재확인.
Reference in New Issue View Git Blame Copy Permalink