llm-wiki/AGENTS.md

LLM Wiki — Agent Operating Rules

본 파일은 Antigravity CLI / Codex CLI / 기타 universal agent CLI 가 세션 시작 시 자동 로드하는 entry point 다. Claude Code 는 별도로 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
파일·디렉토리·branch prefix 명명 규칙	새 파일 slug 결정 시	rules/naming-conventions.md
tags: 5계층 허용 어휘	frontmatter tags 채울 때	rules/tag-taxonomy.md
Evidence matrix + 명명된 실패 모드 + subagent dispatch	multi-doc research / review / audit 시	rules/evidence-first-research.md
보고서 §0~§8 + Verdict 산식 + §7.1 self-grep	보고서 작성 시	rules/reporting-standards.md (root SSOT 559줄)
Goal/Assumption/Action 사슬 + Counterargument + Self-grep + 금지어 (7 Contracts)	권고·브레인스토밍·개념 설명·비교·plan 리뷰·direct-answer 시	rules/advisory-depth.md (root SSOT 418줄)
컨퍼런스급 다이어그램 표준 v2 (8항 self-check)	draw.io / Mermaid 작성 시	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/ 문서:

---
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.

작업 우선순위 + 출력 언어

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 는 모든 모델 공통 SSOT.