161 lines
13 KiB
Markdown
161 lines
13 KiB
Markdown
# 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 모든 칸이 세 플랫폼에서 채워졌는지 재확인.
|