feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00
parent cfd84875bf
commit 58515ab0f3
251 changed files with 31470 additions and 109 deletions
@@ -0,0 +1,208 @@
+# 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 에서 작업해도 산출물의 형식·검증 기준은 일치합니다.