llm-wiki/AGENTS.md

# LLM Wiki — Agent Operating Rules

본 파일은 **Antigravity CLI / Codex CLI / 기타 universal agent CLI** 가 세션 시작 시 자동 로드하는 entry point 다. Claude Code 는 별도로 [`CLAUDE.md`](CLAUDE.md) 를 자동 로드한다 (본 파일과 동일 정책의 풀버전).

> **이 저장소는 무엇인가:** 원본 자료 (`raw/`) 를 **검증된 실무 기술 문서** (`wiki/concepts/` · `wiki/projects/`) 로 변환하고, 그로부터 외부 산출물 (interview / portfolio / blog) 을 파생하는 **파이프라인**. 주된 도메인: 백엔드 / 인프라.

## 최상위 원칙

```
raw 자료는 증거다.
wiki/concepts 와 wiki/projects 는 검증된 실무 기술 문서 (canonical) 이다.
interview / portfolio / blog 는 canonical 에서만 파생된 산출물이다.
```

파생 산출물 (`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`) 은 **반드시** canonical 경유. raw 또는 daily/branch 에서 직접 파생 금지.

## 디렉터리 layout

| 위치 | 역할 |
|---|---|
| `raw/` | 가공 전 원본 자료 (영구 보관: `branch-notes/`, `daily-notes/`) |
| `wiki/` | 정리된 재사용 가능 지식 (`concepts/` · `projects/` · `interview/` · `portfolio/` · `blog/`) |
| `templates/` | 카테고리별 출력 형식 정의 (27개, `templates/blog-topic-template.md` 포함) |
| `rules/` | **3개 모델 공유 SSOT** — 14개 rule (Claude / Antigravity / Codex 동일 본문) |
| `.agents/plugins/wiki-superpowers/` | Antigravity plugin — skills / agents / rules-split |
| `.codex/agents/` | Codex CLI agent manual-invoke definitions |
| `.claude/` | Claude Code skill + slash commands |
| `docs/superpowers/specs/` | multi-doc 보고서 저장 위치 |

## 핵심 rules (lazy-load, 필요 시점 정독)

| Rule | 필독 시점 | 위치 |
|---|---|---|
| Upward link + slug + frontmatter + tag + Cluster + Derived 게이트 | 새 raw / wiki 문서 작성 시 | [`rules/linking-rules.md`](rules/linking-rules.md) |
| 파일·디렉토리·branch prefix 명명 규칙 | 새 파일 slug 결정 시 | [`rules/naming-conventions.md`](rules/naming-conventions.md) |
| `tags:` 5계층 허용 어휘 | frontmatter `tags` 채울 때 | [`rules/tag-taxonomy.md`](rules/tag-taxonomy.md) |
| Evidence matrix + 명명된 실패 모드 + subagent dispatch | multi-doc research / review / audit 시 | [`rules/evidence-first-research.md`](rules/evidence-first-research.md) |
| 보고서 §0~§8 + Verdict 산식 + §7.1 self-grep | 보고서 작성 시 | [`rules/reporting-standards.md`](rules/reporting-standards.md) (root SSOT 559줄) |
| Goal/Assumption/Action 사슬 + Counterargument + Self-grep + 금지어 (7 Contracts) | 권고·브레인스토밍·개념 설명·비교·plan 리뷰·direct-answer 시 | [`rules/advisory-depth.md`](rules/advisory-depth.md) (root SSOT 418줄) |
| 컨퍼런스급 다이어그램 표준 v2 (8항 self-check) | draw.io / Mermaid 작성 시 | [`rules/diagram-standards.md`](rules/diagram-standards.md) (root SSOT 379줄) |

## Plugin entry (Antigravity)

문서 작업 시작 시 invoke:

```
.agents/plugins/wiki-superpowers/skills/wiki-workflow/SKILL.md
```

본 skill 이 dispatch decision tree + STOP self-check + Output-Format Hard Gate 를 강제. 10 agents (`wiki-doc-author`, `wiki-source-summarizer`, `wiki-research-lane`, `wiki-link-verifier`, `wiki-adversarial-reviewer`, `wiki-diagram-reviewer`, `wiki-decision-researcher`, `branch-depth-auditor`, `coverage-auditor`, `wiki-consistency-auditor`) 가 정의되어 있음.

## Frontmatter 표준

모든 `wiki/` 문서:

```yaml
---
title: <문서 제목>
source_type: official-doc | company-tech-blog | personal-blog | lecture | project-note | error-note | job-posting | blog-topic | interview-prep | daily-note | branch-note | concept | interview | portfolio | blog | llm-generated
status: raw | draft | reviewed | verified | published-ready | stale | needs-confirmation
confidence: high | medium | low | unknown
tags: [<l1>, <l2>, ...]
related_projects: [<project>]
last_reviewed: YYYY-MM-DD
---
```

`raw/` 는 최소한 `title`, `source_type`, `url`(있다면), `tags` 만 있어도 됨.

## Source 신뢰도

| source_type | 취급 |
|---|---|
| `official-doc` | 기준 / 정의로 사용 가능 |
| `company-tech-blog` | 사례·관점. **공식 best practice 로 취급 금지** |
| `personal-blog` | 참고 자료 |
| `lecture` | 학습 자료 |
| `blog-topic` | 채용공고가 아닌 작업·학습·트러블슈팅 기반 블로그 글감 원석 |
| `llm-generated` | 검토 전 초안. **high confidence 금지** |

## Project 증거 등급 (외부 공개 가능 여부)

- `actually-implemented` — 코드 존재 ✓
- `locally-verified` — 로컬·dev 환경 확인 ✓
- `prod-verified` — 운영 환경 검증 (로그·측정·인시던트) ✓
- `documented-only` — 문서에만 ❌ 외부 공개 금지
- `planned` — 계획만 ❌ 외부 공개 금지
- `needs-confirmation` — 확인 필요 ❌ 외부 공개 금지

`wiki/interview/` · `wiki/portfolio/` · `wiki/blog/` 작성 시 위 ✓ 등급만 허용.

## 절대 금지

- 출처 없는 단정적 진술
- 공식 문서와 기술블로그 혼동
- `documented-only` / `planned` 를 `actually-implemented` 처럼 표현
- LLM 생성 내용을 검증 없이 `high` confidence 로 분류
- **파생 산출물 (`wiki/interview/`, `wiki/portfolio/`, `wiki/blog/`) 을 canonical 경유 없이 생성**
- **원천 canonical status 가 `reviewed | verified | published-ready` 미만인 상태에서 파생 생성**
- **`/ingest` 로 `wiki/interview/` · `wiki/portfolio/` · `wiki/blog/` 에 문서 작성**
- **branch-note slug 에 numbered hierarchy 사용** (`feature-X-1` 등). slug 는 **구현 내용** 4~8 단어 영문 kebab-case. 계층은 frontmatter `parent_branch:` + `## Parent` 섹션으로만.
- **`develop-` prefix 사용** — 제거됨. 기능 구현 작업은 규모 무관 `feature-`.
- 금지 마케팅 단어 (`100%`, `완벽`, `극한`, `절대로`, `최강`, `역사상 가장`, `명품`) 를 verbatim quote 밖에서 사용

## 파이프라인 게이트 (CLAUDE.md §15 핵심)

| 명령 | 입력 | 출력 | 게이트 |
|---|---|---|---|
| `/ingest` | `raw/*` | `wiki/concepts/` · `wiki/projects/` **만** | — |
| `/projectize` | `wiki/concepts/` | `wiki/projects/` **만** | 원천 status ≥ `reviewed` 권장 |
| `/interviewize` | `wiki/concepts/` · `wiki/projects/` | `wiki/interview/` | 원천 status ∈ {reviewed, verified, published-ready} — 미달 시 중단 |
| `/blogify` | `wiki/concepts/` · `wiki/projects/` | `wiki/blog/` | 동상 |
| (수동) | `wiki/projects/` | `wiki/portfolio/` | 본문 등급은 §"Project 증거 등급" 준수 |

## Runtime hook enforcement (Antigravity 한정)

`~/.gemini/antigravity-cli/hooks/wiki_hard_gate.py` (PreToolUse) 가 `docs/superpowers/specs/*.md` write 시 G1~G4 자동 검사:

- G1: §7.1 의 `$ sed -n` / `$ grep -nF` 명령 존재
- G2: 금지 마케팅 단어 7개 (verbatim quote 밖)
- G3: `Verdict: COMPLETE` + §3-1 산식 (`M==N AND P==R`) 표기
- G4: ≥5 findings master 에 §4-1 Adversarial Review 존재

**Hook 통과 ≠ 합격.** chat 본문 응답, 증거 진실성 (실제 sed/grep 실행), subagent dispatch 판단, 다른 경로 write 등은 모두 agent self-check 단독 책임. 자세히: [`~/.gemini/antigravity-cli/hooks/README.md`](file:///home/donghyeon/.gemini/antigravity-cli/hooks/README.md).

## 작업 우선순위 + 출력 언어

1. 사실 정확성 > 표현 매끄러움
2. 출처 명시 > 빠른 작성
3. 과장 방지 > 강한 어조
4. 재사용 가능성 > 단발성 완성도

본문 산문은 **한국어** 기본. 코드 / CLI 명령 / 공식 용어 (`connection pool`, `idempotent` 등) 는 원문 유지.

## 전체 CLAUDE.md 본문이 필요할 때

본 AGENTS.md 는 CLAUDE.md 의 ≤150줄 요약. 상세 (§4 metadata, §6 등급, §11 절대 금지 전체, §15 파이프라인, §16 품질 10항목 등) 가 필요하면 [`CLAUDE.md`](CLAUDE.md) 직접 정독. CLAUDE.md 는 모든 모델 공통 SSOT.