209 lines
9.7 KiB
Markdown
209 lines
9.7 KiB
Markdown
# Codex Agent Prompts — LLM Wiki
|
||
|
||
이 디렉토리는 LLM Wiki 의 **9개 wiki agent** 를 Codex CLI 에서 사용할 수 있는 프롬프트 템플릿입니다. `.claude/agents/` 의 Claude Code agent 와 본문은 동일하지만 **frontmatter 에서 `tools:` 와 `model:` 필드를 제거**했습니다 (Codex 는 이 필드를 자동 파싱하지 않음). 본문 안의 `Read tool` / `Edit tool` / `Write tool` / `Bash tool` 같은 Claude Code 전용 표현도 `Read` / `Edit` / `Write` / `shell` 로 일반화했습니다. 같은 `rules/` 와 `templates/` 를 참조합니다.
|
||
|
||
## Native generation (현재 방식)
|
||
|
||
Codex CLI 는 **native subagent 를 `.codex/agents/*.toml` 로 등록**한다 (`name` / `description` / `developer_instructions` + `sandbox_mode`). SSOT 는 **`.agents/plugins/wiki-superpowers/agents/<name>.md`** (gated body) 이고, 이 디렉토리의 `.md` 와 `.toml` 은 그 대응 variant 이다.
|
||
|
||
> ⚠️ **자동 생성기 `scripts/sync_automation.py` 는 현재 repo 에 없다**(2026-06-06 확인; `scripts/` 는 존재하나 `sync_automation.py` 만 부재 — 2026-07-14 재확인). 아래 명령은 생성기가 복원되면 쓰는 *의도된* 경로이며, 그 전까지는 **SSOT `.md` 편집 시 대응 `.toml` 을 수기로 맞춰** 3 플랫폼 패리티를 유지한다.
|
||
|
||
```bash
|
||
# (생성기 복원 시) .md (+ .claude/agents frontmatter tools:) -> .toml
|
||
python3 scripts/sync_automation.py agents
|
||
python3 scripts/sync_automation.py agents --check # exit 2 on drift (CI 용)
|
||
```
|
||
|
||
**Commands(슬래시 명령) 도 같은 (현재 부재) 스크립트로 동기화되도록 설계됐다.** `.claude/commands/*.md` (현재 23개 — invest-* 6 + `project`/`project-spec` 2 = 8개는 Claude 전용 비동기화, 나머지 15개가 mirror) 를 SSOT 로:
|
||
|
||
```bash
|
||
# (생성기 복원 시) -> .agents/skills/<cmd>/SKILL.md (codex) + .agents/workflows/<cmd>.md (antigravity)
|
||
python3 scripts/sync_automation.py commands
|
||
python3 scripts/sync_automation.py commands --check # exit 2 on drift
|
||
```
|
||
|
||
Codex 는 `.agents/skills/<cmd>/SKILL.md` 를 skill 로 자동 디스커버리하고 `$<cmd>` / `/skills` 로 호출한다. 인자는 placeholder 없이 자연어(각괄호 prose). Antigravity 는 `.agents/workflows/<cmd>.md` 를 `/<cmd>` 슬래시로 인식한다.
|
||
|
||
`.md` SSOT 를 편집한 뒤 대응 `.toml` 을 갱신해야(생성기 부재 시 **수기**) `.toml` 에 반영된다. 권한은 `.claude/agents/<name>.md` frontmatter 의 `tools:` 에서 파생된다 — `Edit`/`Write` 가 있으면 `sandbox_mode = "workspace-write"`, 없으면 `"read-only"`.
|
||
|
||
> 아래 "Pattern" 의 `codex exec "$(cat ...md)"` 수동 호출은 native `.toml` 자동 등록 이전의 **legacy** 방식이다. 일회성 실행에는 여전히 쓸 수 있으나, 표준 경로는 위 native `.toml` 이다.
|
||
|
||
## Pattern
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s read-only \
|
||
"$(cat .codex/agents/wiki-link-verifier.md)
|
||
|
||
Scope: project:keycloak-patterns"
|
||
```
|
||
|
||
### Sandbox 권장 설정
|
||
|
||
| Agent | 권장 sandbox |
|
||
|---|---|
|
||
| `wiki-doc-author` (mode=create / migrate) | `-s workspace-write` (파일 생성·수정 필요) |
|
||
| `wiki-source-summarizer` | `-s workspace-write` (raw/ 에 파일 생성) |
|
||
| `wiki-link-verifier` | `-s read-only` (audit only) |
|
||
| `wiki-research-lane` | `-s read-only` (synthesis recommendation only) |
|
||
| `wiki-adversarial-reviewer` | `-s read-only` (falsification only) |
|
||
| `wiki-diagram-reviewer` | `-s read-only` (scoring only) |
|
||
| `wiki-decision-researcher` | `-s workspace-write` (wiki-source-summarizer 디스패치로 raw 자료 N×2개 생성) |
|
||
|
||
write 권한을 read-only agent 에 주면 오용 위험. read-only 도구에 workspace-write 부여 금지.
|
||
|
||
## Scope
|
||
|
||
LLM Wiki 의 `.codex/agents/` 는 **문서 작업 전용** — 7개 prompt:
|
||
|
||
- `wiki-doc-author` — 새 raw 문서 생성 + 기존 비-template 문서 마이그레이션 (1 dispatch = 1 논리적 문서 (target + Parent hub); supports branch-note, error-note, interview-prep, job-posting, blog-topic, lecture-note, project-note, daily-note)
|
||
- `wiki-source-summarizer` — 외부 URL → raw 자료 보존 (verbatim quote + self-grep)
|
||
- `wiki-link-verifier` — orphan / broken wikilink / Cluster 누락 감사 (read-only)
|
||
- `wiki-research-lane` — 다수 raw 정독 → 합성 권고 (read-only)
|
||
- `wiki-adversarial-reviewer` — 리서치/감사 draft falsification (read-only)
|
||
- `wiki-diagram-reviewer` — `.drawio` 다이어그램 컨퍼런스급 채점 (read-only)
|
||
- `wiki-decision-researcher` — 기술 결정 alternatives orchestrator (WebSearch + URL 후보 + wiki-source-summarizer dispatch + 비교 매트릭스 + 조건부 권고)
|
||
|
||
**코드 작업 (Java / Clean Architecture)** 은 본 vault 범위 밖. ca-tmpl 의 `.codex/agents/` (`ca-implementer`, `ca-architect-sentinel`, `ca-spec-reviewer`, `ca-quality-reviewer`, `gradle-runner`) 사용.
|
||
|
||
## Workflow Contracts
|
||
|
||
7개 prompt 모두 다음 top-level rules 를 참조합니다 — Codex CLI 는 자동 로드하지 않으므로 호출 시 explicit 으로 전달:
|
||
|
||
- `rules/linking-rules.md`
|
||
- `rules/naming-conventions.md`
|
||
- `rules/tag-taxonomy.md`
|
||
- `rules/diagram-standards.md`
|
||
- `rules/evidence-first-research.md`
|
||
- `rules/reporting-standards.md`
|
||
- `rules/advisory-depth.md`
|
||
|
||
각 agent 의 **Mandatory First Reads** 섹션에 어떤 rule 을 정독해야 하는지 명시되어 있습니다.
|
||
|
||
## Codex 호출 예시
|
||
|
||
### 1. 새 branch-note 생성
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s workspace-write \
|
||
"$(cat .codex/agents/wiki-doc-author.md)
|
||
|
||
Mode: create
|
||
Category: branch-note
|
||
Title: 'branch / feature-keycloak-patterns (root)'
|
||
File slug: feature-keycloak-patterns
|
||
Parent: keycloak-patterns (project slug)
|
||
Sources: 필요시 채움 (feature- prefix 면 ≥1개 필수)
|
||
Initial seed: OIDC 패턴 학습 작업 묶음"
|
||
```
|
||
|
||
### 2. 기존 비-template 노트 마이그레이션
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s workspace-write \
|
||
"$(cat .codex/agents/wiki-doc-author.md)
|
||
|
||
Mode: migrate
|
||
Category: error-note
|
||
Title: 'error / Keycloak OIDC discovery 실패 (2026-05-25)'
|
||
Target path: raw/errors/oidc-discovery-failure-2026-05-25.md
|
||
Parent: feature-keycloak-patterns-1-1 (branch slug)"
|
||
```
|
||
|
||
### 3. URL → raw 자료 보존
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s workspace-write \
|
||
"$(cat .codex/agents/wiki-source-summarizer.md)
|
||
|
||
URL: https://www.keycloak.org/docs/latest/securing_apps/#_oidc
|
||
source_type: official-doc
|
||
Parent: feature-keycloak-patterns-1-1
|
||
이 자료가 정당화하는 결정: oauth2-proxy provider=keycloak-oidc 설정 근거"
|
||
```
|
||
|
||
### 4. 링크 무결성 감사
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s read-only \
|
||
"$(cat .codex/agents/wiki-link-verifier.md)
|
||
|
||
Scope: project:keycloak-patterns"
|
||
```
|
||
|
||
### 5. 다수 raw 정독 + 합성 권고
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s read-only \
|
||
"$(cat .codex/agents/wiki-research-lane.md)
|
||
|
||
Slice:
|
||
- raw/branch-notes/feature-keycloak-patterns-1-1.md
|
||
- raw/branch-notes/feature-keycloak-patterns-1-2.md
|
||
- raw/official-docs/oidc-discovery-keycloak-official.md
|
||
Research question: 이 3개 노트에서 wiki/concepts/oidc-handshake 로 추출할 핵심 사실 식별
|
||
Target output type: wiki-concept-draft"
|
||
```
|
||
|
||
### 6. Adversarial review
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s read-only \
|
||
"$(cat .codex/agents/wiki-adversarial-reviewer.md)
|
||
|
||
Master report path: docs/superpowers/specs/2026-05-26-keycloak-audit-report.md
|
||
Per-file findings path: docs/superpowers/specs/2026-05-26-keycloak-audit-per-file-findings.md
|
||
Source corpus: raw/branch-notes/"
|
||
```
|
||
|
||
### 7. 다이어그램 채점
|
||
|
||
```bash
|
||
codex exec \
|
||
-C /home/donghyeon/Documents/LLM\ Wiki \
|
||
-s read-only \
|
||
"$(cat .codex/agents/wiki-diagram-reviewer.md)
|
||
|
||
Target diagrams:
|
||
- raw/diagrams/keycloak-patterns/architecture-overview-2026-05-26.drawio
|
||
- raw/diagrams/keycloak-patterns/architecture-deployment-2026-05-26.drawio
|
||
Standards file: rules/diagram-standards.md"
|
||
```
|
||
|
||
## Recommended Workflow
|
||
|
||
문서 작업의 표준 흐름:
|
||
|
||
1. **캡처**: `wiki-doc-author` (mode=create) 또는 `wiki-source-summarizer` 로 raw 자료 등록
|
||
2. **검증**: `wiki-link-verifier` 로 새 raw 가 cluster 에 올바르게 연결되었는지 점검
|
||
3. **합성**: 충분한 raw 가 모이면 `wiki-research-lane` 으로 wiki/concepts 또는 wiki/projects 추출 권고
|
||
4. **검수**: findings ≥ 5 인 큰 보고서면 `wiki-adversarial-reviewer` 로 falsification
|
||
5. **다이어그램**: project-note 의 `.drawio` 가 생성·수정되면 `wiki-diagram-reviewer` 로 ≥95 점 확인
|
||
|
||
기존 비-template 문서가 있다면 `wiki-doc-author` (mode=migrate) 로 normalize 후 위 흐름 진입.
|
||
|
||
## Note: 다른 CLI 와의 일관성
|
||
|
||
본 `.codex/agents/` 의 7개 파일은 `.claude/agents/` 와 본문 내용이 같지만, frontmatter 와 tool 표현이 codex 환경에 맞춰 정리되어 있습니다 — `tools:`/`model:` 필드 제거, 본문의 `Read tool`/`Edit tool` 등은 일반화. Claude Code 와 Codex 는 같은 작업 정의를 공유하지만 invocation 방식이 다릅니다:
|
||
|
||
| CLI | Agent 파일 위치 | 자동 등록 | Skill 폴더 | frontmatter | 특수 기능 |
|
||
|---|---|---|---|---|---|
|
||
| Claude Code | `.claude/agents/` | ✓ | `.claude/skills/` | `tools:` + `model: sonnet` 유지 | Skill 이 dispatch decision tree 처리 |
|
||
| Codex | `.codex/agents/` | ✗ (수동 cat + exec) | (없음) | `tools:` / `model:` 제거됨 | `-s` sandbox flag 로 권한 제어 |
|
||
| Antigravity | `.agents/plugins/wiki-superpowers/agents/` | ✓ (plugin) | `.agents/plugins/wiki-superpowers/skills/` | `tools:` / `model:` 없음, G1~G4 hard gates | Gemini 4가지 실패 모드 차단 |
|
||
|
||
3개 모두 동일한 `rules/` 와 `templates/` 를 참조하므로, 어느 CLI 에서 작업해도 산출물의 형식·검증 기준은 일치합니다.
|