Forgen

Claude Code 개인화 하네스.
쓸수록 나를 더 잘 아는 Claude.

npm version License: MIT Node.js >= 20

비전 · 동작 흐름 · 빠른 시작 · 동작 방식 · 4축 개인화 · 명령어 · 아키텍처 · 안전

English · 한국어 · 日本語 · 简体中文

--- ## 두 개발자. 같은 Claude. 완전히 다른 행동. 개발자 A는 신중합니다. Claude가 모든 테스트를 돌리고, 이유를 설명하고, 현재 파일 밖의 것은 손대기 전에 물어봐야 합니다. 개발자 B는 빠릅니다. Claude가 가정하고, 관련 파일까지 바로 고치고, 결과를 두 줄로 보고하면 됩니다. forgen 없이는 두 개발자 모두 같은 범용 Claude를 받습니다. forgen를 쓰면, 각자 자기 방식대로 일하는 Claude를 받습니다. ``` 개발자 A의 Claude: 개발자 B의 Claude: "관련 이슈 3개를 발견했습니다. "로그인 + 관련 파일 2개 수정 완료. 진행하기 전에 세션 핸들러도 테스트 통과. 리스크 1건: 세션 함께 수정할까요? 각각의 분석은 타임아웃 미커버. 끝." 다음과 같습니다..." ``` forgen가 이것을 가능하게 합니다. 작업 스타일을 프로파일링하고, 교정에서 학습하고, Claude가 매 세션마다 따르는 개인화 규칙을 렌더링합니다. --- ## 하네스가 당신을 담고 간다 개인화는 표면입니다. 더 깊은 아이디어: **매 세션이 흔적을 남기고, 그 흔적들이 쌓여 당신처럼 판단하는 하네스가 됩니다.** 교정, 컨벤션, 트레이드오프 선호 — 대화에서 추출되어 `~/.forgen/me/` 에 저장되고, 다음 세션마다 Claude 에 다시 주입됩니다. ``` 대화 ──► 추출: solution / rule / behavior / profile 업데이트 ────────────────────────────────────────────── │ ▼ 다음 세션 ◄── 주입: UserPromptSubmit 컨텍스트 + 렌더된 규칙 + 당신의 기준에 맞춘 Stop-hook 가드 ``` 몇 주가 지나면 이 하네스는 "규칙을 강제하는 도구"가 아니라 **당신이 일을 판단하는 방식이 담긴 휴대 가능한 번들** 이 됩니다. 한 줄로 export: ```bash forgen compound export # → forgen-knowledge-YYYY-MM-DD.tar.gz # (rules + solutions + behavior — 당신의 철학) forgen compound import # 다른 머신에서 그대로 재연 ``` 그게 북극성입니다: *노트북 위에 있는, 당신처럼 판단하는 Claude, 그리고 들고 다닐 수 있는 tarball.* --- ## forgen를 쓰면 일어나는 일 ### 첫 실행 (1회, 약 1분) ```bash npm install -g @wooojin/forgen forgen ``` 첫 실행을 감지하면 4문항 온보딩이 시작됩니다. 각 질문은 구체적인 시나리오입니다: ``` 질문 1: 애매한 구현 요청 "로그인 기능을 개선해줘"라는 요청을 받았습니다. 요구사항이 명확하지 않고, 인접 모듈에 영향을 줄 수 있습니다. A) 먼저 요구사항/범위를 확인하고, 범위 확대 가능성이 있으면 물어본다 B) 같은 흐름 안이면 진행하되, 큰 범위 확대가 보이면 확인한다 C) 합리적으로 가정하고 인접 파일까지 바로 수정한다 선택 (A/B/C): ``` 4개의 질문. 4개의 축 측정. 각 축에 팩과 세밀한 facet이 포함된 프로필이 생성됩니다. 개인화된 규칙 파일이 렌더링되어 Claude가 읽는 위치에 배치됩니다. ### 매 세션 (일상 사용) ```bash forgen # `claude` 대신 사용 ``` 내부 동작: 1. 하네스가 `~/.forgen/me/forge-profile.json`에서 프로필 로드 2. 프리셋 매니저가 세션 합성: 글로벌 안전 규칙 + 팩 기본 규칙 + 개인 오버레이 + 세션 오버레이 3. 규칙 렌더러가 모든 것을 자연어로 변환하여 `~/.claude/rules/v1-rules.md`에 기록 4. Claude Code가 시작되어 해당 규칙을 행동 지침으로 읽음 5. 안전 훅 활성화: 위험 명령 차단, 시크릿 필터링, 프롬프트 인젝션 탐지 ### Claude를 교정할 때 당신이 말합니다: "내가 요청하지 않은 파일은 리팩토링하지 마." Claude가 `correction-record` MCP 도구를 호출합니다. 교정은 축 분류(`judgment_philosophy`), 종류(`avoid-this`), 신뢰도 점수가 포함된 구조화된 evidence로 저장됩니다. 현재 세션에 즉시 효과를 주는 임시 규칙이 생성됩니다. ### 세션 사이 (자동) 세션이 끝나면 auto-compound가 추출합니다: - 솔루션 (맥락이 포함된 재사용 가능한 패턴) - 행동 관찰 (당신의 작업 방식) - 세션 학습 요약 축적된 evidence를 기반으로 facet이 미세 조정됩니다. 교정이 지속적으로 현재 팩과 다른 방향을 가리키면, 3세션 후 mismatch 감지가 트리거되어 팩 변경을 추천합니다. ### 다음 세션 교정이 반영된 업데이트 규칙이 렌더링됩니다. Compound 지식이 MCP를 통해 검색 가능합니다. Claude가 *당신의* Claude가 되어갑니다. --- ## 빠른 시작 ```bash # 1. 설치 (반드시 -g — forgen 은 글로벌 CLI) npm install -g @wooojin/forgen # 2. 호스트 등록 — Claude Code / Codex / 양쪽 forgen install both # 3지선다 인터랙티브: claude / codex / both # 또는 비대화형: forgen install claude forgen install codex # 3. 첫 실행 — 4문항 온보딩 (영어/한국어 선택) forgen # 기본: Claude forgen --runtime codex # Codex 로 실행 forgen config default-host codex # 영구 기본 호스트 설정 ``` ### 사전 요구사항 - **Node.js** >= 20 (SQLite 세션 검색은 >= 22 권장) - **하나 이상의 호스트** 설치 및 인증: - **Claude Code** — `npm i -g @anthropic-ai/claude-code` - **Codex CLI** — [Codex docs](https://github.com/openai/codex) 참고 - 둘 다 사용 가능 — `forgen install both` 가 양쪽에 hook/MCP 를 대칭 등록 > **벤더 의존성:** forgen 은 Claude Code 와 Codex CLI 를 대칭 래핑합니다 (Claude 가 동작 기준, Codex 가 동등성 확장). 상위 API/CLI 변경이 동작에 영향을 줄 수 있습니다. Claude Code 1.0.x / 2.1.x, Codex 0.x 에서 테스트됨. ### 격리 / CI / Docker 사용 forgen 홈은 기본 `~/.forgen` 이지만 프로세스별 override 가능: ```bash # 깨끗한 격리 홈 — 실제 ~/.forgen 은 건드리지 않음 FORGEN_HOME=/tmp/forgen-clean forgen init # starter-pack 15개 자동 배포 FORGEN_HOME=/tmp/forgen-clean forgen stats # 격리 홈의 통계만 표시 FORGEN_HOME=/tmp/forgen-clean claude -p "…" # 훅이 env 상속 → 격리된 로그 ``` Claude Code 훅 프로세스가 부모 env 를 상속하므로 `FORGEN_HOME=...` 프리픽스 하나면 모든 상태(rules/solutions/behavior/enforcement)가 해당 디렉터리로 격리. 쓰임새: - CI 파이프라인에서 고정 시드로 forgen 검증 - 실 홈 오염 없이 "신규 사용자 첫날 경험" 재현 - 한 머신에서 여러 페르소나 운영 **Docker / 원격 서버 (OAuth 제약):** Claude Code 는 OAuth 세션을 **OS 키체인** (macOS Keychain / libsecret / Windows Credential Manager) 에 저장하므로, 새 Linux 컨테이너에서 `~/.claude.json` 만 마운트하면 refresh 토큰이 없어서 인증이 안 됩니다. 컨테이너 환경에서는 `ANTHROPIC_API_KEY` env 를 사용하세요. 호스트 기반 사용(macOS/Linux 워크스테이션) 은 `claude login` 흐름 그대로 동작 — API 키 불필요. ### 마이그레이션 `forgen migrate implicit-feedback` — pre-v0.4.1 로그의 `category` 필드 백필. 멱등(idempotent) — 여러 번 실행 안전. --- ## 왜 forgen인가 | | Generic Claude Code | oh-my-claudecode | forgen | |------------------------|:-------------------:|:----------------:|:---------------:| | 모두에게 동일 | Yes | Yes | **No** | | 교정에서 학습 | No | No | **Yes** | | Evidence 기반 라이프사이클| No | No | **Yes** | | 나쁜 패턴 자동 은퇴 | No | No | **Yes** | | 개인화된 규칙 | No | No | **Yes** | | 런타임 의존성 | - | many | **3** | ### 언제 사용하면 좋은가 **잘 맞는 경우:** - 몇 주에 걸쳐 Claude가 패턴을 학습하는 장기 프로젝트 - AI 행동 방식에 강한 선호가 있는 개발자 - Compound 지식의 혜택을 받는 반복 패턴이 있는 코드베이스 **맞지 않는 경우:** - 일회성 스크립트나 임시 프로토타입 - Claude Code가 없는 환경 - 모든 구성원이 동일한 AI 행동이 필요한 팀 (forgen은 개인용이지, 팀용이 아님) **forgen + oh-my-claudecode:** 함께 사용할 수 있습니다. OMC는 오케스트레이션(에이전트, 워크플로우)을, forgen은 개인화(프로필, 학습)를 담당합니다. [공존 가이드](docs/guides/with-omc.md)를 참고하세요. --- ## 동작 방식 ### 학습 루프 ``` +-------------------+ | 온보딩 | | (4문항) | +--------+----------+ | v +-------------------------------+ | 프로필 생성 | | 4축 x 팩 + facet + trust | +-------------------------------+ | +-----------------------+------------------------+ | | v | +------------------+ | | 규칙 렌더링 | ~/.claude/rules/v1-rules.md | | Claude 형식으로 | | +--------+---------+ | | | v | +------------------+ | | 세션 진행 | Claude가 개인화 규칙을 따름 | | 교정하면 | ---> correction-record MCP | | Claude 학습 | Evidence 저장 | +--------+---------+ 임시 규칙 생성 | | | v | +------------------+ | | 세션 종료 | auto-compound 추출: | | | 솔루션 + 관찰 + 요약 | +--------+---------+ | | | v | +------------------+ | | Facet 조정 | 프로필 미세 조정 | | Mismatch 확인 | 최근 3세션 rolling 분석 | +--------+---------+ | | | +------------------------------------------------+ (다음 세션: 업데이트된 규칙) ``` ### 2-layer 안전 적용 학습된 제약이 모델이 우회를 시도해도 유지되도록 forgen은 **두 단계**에서 적용됩니다: | 단계 | Hook | 시점 | 차단 대상 | |---|---|---|---| | **Soft (컨텍스트)** | UserPromptSubmit (`notepad-injector`) | 매 turn 시작 전 | 활성 룰을 Claude 컨텍스트에 재주입 — 모델이 자율 준수하도록 유도. | | **Hard (도구)** | PreToolUse (`pre-tool-use` + `dangerous-patterns.json`) | 모든 Bash / Edit / Write 직전 | `rm -rf /`, `git push --force`, `DROP TABLE`, `mkfs`, `curl \| sh` 등 패턴 매칭 차단 — 모델 의도 무관하게 발동. | | **Hard (응답)** | Stop (`stop-guard` DANGEROUS-RESPONSE) | Claude 응답 직후 | 응답 텍스트 자체 패턴 매칭 — *제안된* 파괴 명령(예: `find … -exec rm`, `xargs rm` 우회)을 사용자가 보기 전에 차단. | Soft layer는 모델에게 "지켜줘"라고 요청하고, Hard layer는 요청하지 않습니다. driver 모델이 약해서 학습된 룰을 "창의적으로" 우회하려 해도 (예: `rm -rf` 금지 → `find -exec rm -r` 제안) Hard layer가 미리 차단합니다. 오버라이드: 한 turn만 감사 우회는 `FORGEN_USER_CONFIRMED=1`, 특정 룰 영구 비활성화는 `forgen suppress-rule `. ### Compound 지식 지식은 세션을 거치며 신뢰도 기반 라이프사이클로 축적됩니다: ``` experiment (0.30) → candidate (0.55) → verified (0.75) → mature (0.90) ``` 각 솔루션은 `experiment`로 시작합니다. 세션을 거치며 코드에 반영될수록 자동 승격됩니다. 부정적 evidence는 서킷 브레이커를 작동시켜 자동 은퇴시킵니다. 실제로 당신에게 맞는 패턴만 살아남습니다. | 유형 | 출처 | Claude 활용 방법 | |------|------|-----------------| | **솔루션** | 세션에서 추출 | 프롬프트와 관련 있을 때 자동 주입 (TF-IDF + BM25 + bigram 앙상블) | | **스킬** | 10개 내장 + 검증된 솔루션에서 승격 | 키워드로 활성화 (`deep-interview`, `forge-loop`, `ship` 등) | | **행동 패턴** | 3회 이상 관찰 시 자동 감지 | `forge-behavioral.md`에 적용 | | **Evidence** | 교정 + 관찰 | facet 조정 및 규칙 생성의 근거 | ### Solution 자동 주입 입력하는 모든 프롬프트가 축적된 솔루션과 매칭됩니다. 관련 솔루션은 Claude의 컨텍스트에 자동 주입됩니다 — 직접 찾아볼 필요가 없습니다. ``` 입력: "API의 에러 핸들링을 고쳐줘" ↓ solution-injector 매칭: starter-error-handling-patterns (0.70) ↓ Claude에게 전달: "매칭된 솔루션: error-handling-patterns [pattern|0.70] 특정 에러 타입으로 try/catch 사용. 원본 에러는 반드시 로깅..." ↓ Claude가 축적된 패턴을 바탕으로 더 나은 에러 핸들링 코드를 작성합니다. ``` ### 10개 내장 스킬 엄선된 compound-native 스킬. 모든 스킬이 축적된 지식과 연동 — 쓸수록 정확해집니다. **핵심 체인** (빌드 → 학습): | 스킬 | 트리거 | 기능 | |------|--------|------| | `deep-interview` | "deep-interview", "딥인터뷰" | 가중 4차원 ambiguity 점수, 3개 챌린지 모드 (Contrarian/Simplifier/Ontologist), 온톨로지 추적 | | `forge-loop` | "forge-loop", "끝까지" | PRD 기반 반복 루프. Stop 훅이 polite-stop 방지. Verifier가 fresh evidence 강제 | | `compound` | "복리화", "compound" | 5-Question 품질 필터로 패턴 추출. Health dashboard 포함 | **관리 체인** (리뷰 → 튜닝): | 스킬 | 트리거 | 기능 | |------|--------|------| | `retro` | "retro", "회고" | 주간 회고: git 분석 + compound 건강도 + 학습 추세 + 3가지 추천 | | `learn` | "learn prune", "compound 정리" | 5개 서브커맨드: search/stats/prune/export/import. Stale & 중복 자동 감지 | | `calibrate` | "calibrate", "프로필 보정" | Evidence 기반 프로필 조정. 한 번에 최대 2개 축. 임계값: 같은 방향 3건+ | **독립 스킬**: | 스킬 | 트리거 | 기능 | |------|--------|------| | `ship` | "ship", "배포" | 15단계 파이프라인. "Never ask, just do" 철학. Review Readiness Dashboard + Verification Gate | | `code-review` | "code review", "리뷰" | 신뢰도 1-10 보정, Critical 5개 카테고리 (SQL/race/LLM trust/secrets/enum), auto-fix | | `architecture-decision` | "adr" | 가중 트레이드오프 매트릭스, ADR 라이프사이클, 가역성 분류 | | `docker` | "docker", "컨테이너" | 멀티스테이지 빌드, 보안 강화, 10개 failure modes | ### 세션 관리 | 기능 | 동작 | |------|------| | **세션 브리프** | 컨텍스트 압축 전 구조화된 브리프 저장 → 다음 세션에서 복원 | | **drift 감지** | EWMA 기반 편집 속도 추적 → 15회 편집 시 경고, 30회 위험, 50회 강제 정지 | | **에이전트 출력 검증** | Claude가 서브 에이전트를 실행할 때 출력 품질 자동 검증 | | **자동 압축** | 누적 12만 자 초과 시 Claude에게 컨텍스트 압축 지시 | | **pending compound** | 20회 이상 프롬프트 세션 후 다음 세션에서 compound 추출 자동 트리거 | --- ## 4축 개인화 각 축에는 3개의 팩이 있습니다. 각 팩에는 세밀한 facet(0-1 수치)이 포함되어 있으며, 교정에 따라 시간이 지나면서 미세 조정됩니다. ### 품질/안전 | 팩 | Claude의 행동 | |----|-------------| | **보수형** | 완료 보고 전 모든 테스트를 실행. 타입 체크. 엣지 케이스 검증. 모든 검사가 통과해야 "완료"라고 말함. | | **균형형** | 핵심 검증을 실행하고, 남은 리스크를 요약. 철저함과 속도의 균형. | | **속도형** | 빠른 smoke 테스트. 결과와 리스크를 즉시 보고. 전달을 우선. | ### 자율성 | 팩 | Claude의 행동 | |----|-------------| | **확인 우선형** | 인접 파일을 수정하기 전 확인. 애매한 요구사항 명확화. 범위 확장에 승인 요청. | | **균형형** | 같은 흐름 안이면 진행. 큰 범위 확대가 보이면 확인. | | **자율 실행형** | 합리적으로 가정. 관련 파일을 바로 수정. 완료 후 무엇을 했는지 보고. | ### 판단 철학 | 팩 | Claude의 행동 | |----|-------------| | **최소변경형** | 기존 구조 유지. 동작하는 코드를 리팩토링하지 않음. 수정 범위를 최소한으로 유지. | | **균형형** | 현재 작업에 집중. 명확한 개선 기회가 보이면 제안. | | **구조적접근형** | 반복 패턴이나 기술 부채를 발견하면 적극적으로 구조 개선 제안. 추상화와 재사용 설계 선호. 아키텍처 일관성 유지. | ### 커뮤니케이션 | 팩 | Claude의 행동 | |----|-------------| | **간결형** | 코드와 결과만. 선제적으로 설명하지 않음. 물어볼 때만 부연. | | **균형형** | 핵심 변경과 이유를 요약. 필요하면 추가 질문 유도. | | **상세형** | 무엇을, 왜, 영향 범위, 대안까지 설명. 교육적 맥락 제공. 보고서를 섹션별로 구조화. | --- ## 렌더링된 규칙의 실제 모습 forgen가 세션을 합성하면 Claude가 읽는 `v1-rules.md` 파일을 렌더링합니다. 서로 다른 프로필이 완전히 다른 Claude 행동을 만드는 두 가지 실제 예시입니다. ### 예시 1: 보수형 + 확인 우선형 + 구조적접근형 + 상세형 ```markdown [보수형 quality / 확인 우선형 autonomy / 구조적접근형 judgment / 상세형 communication] ## Must Not - .env, credentials, API 키를 절대 커밋하거나 노출하지 마라. - 파괴적 명령(rm -rf, DROP, force-push)은 사용자 확인 없이 실행하지 마라. ## Working Defaults - Trust: 위험 우회 비활성. 파괴적 명령, 민감 경로 접근 시 항상 확인. - 반복되는 패턴이나 기술 부채를 발견하면 적극적으로 구조 개선을 제안하라. - 추상화와 재사용 가능한 설계를 선호하라. 단, 과도한 추상화는 피한다. - 변경 시 전체 아키텍처 관점에서 일관성을 유지하라. ## When To Ask - 애매한 작업은 시작 전 요구사항을 명확히 하라. - 명시적으로 요청된 범위 밖의 파일을 수정하기 전에 확인하라. ## How To Validate - 완료 보고 전 관련 테스트, 타입 체크, 핵심 검증을 모두 완료하라. - 모든 검사가 통과하기 전에는 "완료"라고 하지 마라. ## How To Report - 변경 이유, 대안 검토, 영향 범위를 함께 설명하라. - 교육적 맥락을 제공하라 — 왜 이 접근이 좋은지, 다른 방법과 비교. - 보고는 구조화하라 (변경 사항, 이유, 영향, 다음 단계). ## Evidence Collection - 사용자가 행동을 교정하면("하지마", "그렇게 말고", "앞으로는 이렇게") 반드시 correction-record MCP 도구를 호출하여 evidence로 기록하라. - kind 선택: fix-now(즉시 수정), prefer-from-now(앞으로 이렇게), avoid-this(하지 마라) - axis_hint: quality_safety(품질/검증), autonomy(자율/확인), judgment_philosophy(변경 접근법), communication_style(설명 스타일) - 교정이 아닌 일반 피드백은 기록하지 않는다. ``` ### 예시 2: 속도형 + 자율 실행형 + 최소변경형 + 간결형 ```markdown [속도형 quality / 자율 실행형 autonomy / 최소변경형 judgment / 간결형 communication] ## Must Not - .env, credentials, API 키를 절대 커밋하거나 노출하지 마라. - 파괴적 명령(rm -rf, DROP, force-push)은 사용자 확인 없이 실행하지 마라. ## Working Defaults - Trust: 런타임 마찰 최소화. 명시적 금지와 파괴적 명령 외에는 자유 실행. - 기존 코드 구조를 최대한 유지하라. 동작하는 코드를 불필요하게 리팩토링하지 마라. - 수정 범위를 최소한으로 유지하라. 인접 파일 변경은 꼭 필요한 경우에만. - 변경 전 근거(테스트, 에러 로그)를 먼저 확보하라. ## How To Validate - 최소 smoke만 보고 빠르게 결과와 리스크만 보고하라. ## How To Report - 응답은 짧고 핵심만. 코드와 결과 위주로 보고하라. - 부연 설명은 물어볼 때만. 선제적으로 길게 설명하지 마라. ## Evidence Collection - 사용자가 행동을 교정하면("하지마", "그렇게 말고", "앞으로는 이렇게") 반드시 correction-record MCP 도구를 호출하여 evidence로 기록하라. - kind 선택: fix-now(즉시 수정), prefer-from-now(앞으로 이렇게), avoid-this(하지 마라) - axis_hint: quality_safety(품질/검증), autonomy(자율/확인), judgment_philosophy(변경 접근법), communication_style(설명 스타일) - 교정이 아닌 일반 피드백은 기록하지 않는다. ``` 같은 Claude. 같은 코드베이스. 완전히 다른 작업 스타일. 1분짜리 온보딩이 만든 차이입니다. --- ## 명령어 ### 핵심 ```bash forgen # 개인화된 Claude Code 시작 forgen "로그인 버그 수정해줘" # 프롬프트와 함께 시작 forgen --resume # 이전 세션 이어서 ``` ### 개인화 ```bash forgen onboarding # 4문항 온보딩 실행 forgen forge --profile # 현재 프로필 확인 forgen forge --reset soft # 프로필 초기화 (soft / learning / full) forgen forge --export # 프로필 내보내기 ``` ### 상태 확인 ```bash forgen stats # 한 화면 Trust Layer 대시보드 (규칙·교정·block 7일) forgen last-block # 가장 최근 block 이벤트와 rule 상세 forgen inspect profile # 4축 프로필 + 팩 + facet forgen inspect rules # 활성/비활성 규칙 forgen inspect corrections # 교정 기록 (alias: evidence) forgen inspect session # 현재 세션 상태 forgen inspect violations # 최근 block 기록 (--last N) forgen me # 개인 대시보드 (inspect profile 단축키) ``` ### 규칙 관리 ```bash forgen rule list # 활성 + suppressed 규칙 목록 forgen rule suppress # 규칙 비활성화 (hard 규칙은 거부) forgen rule activate # suppressed 규칙 재활성화 forgen rule scan [--apply] # 수명주기 트리거 실행 (승격/강등/은퇴) forgen rule health-scan # drift → Mech 강등 후보 스캔 forgen rule classify # 레거시 규칙에 enforce_via 자동 제안 ``` ### 지식 관리 ```bash forgen compound # 축적된 지식 미리보기 forgen compound --save # 자동 분석된 패턴 저장 forgen compound list # 상태가 포함된 솔루션 전체 목록 forgen compound inspect <이름> # 솔루션 전체 내용 확인 forgen compound --lifecycle # 승격/강등 검사 실행 forgen compound --verify <이름> # 수동으로 verified 승격 forgen compound export # 지식을 tar.gz로 내보내기 forgen compound import <경로> # 지식 아카이브 가져오기 forgen skill promote <이름> # 검증된 솔루션을 스킬로 승격 forgen skill list # 승격된 스킬 목록 ``` ### 시스템 ```bash forgen init # 프로젝트 초기화 forgen doctor # 시스템 진단 (10개 항목 + 하네스 성숙도) forgen dashboard # 지식 현황 대시보드 (6개 섹션) forgen config hooks # 훅 상태 + 컨텍스트 예산 확인 forgen config hooks --regenerate # 훅 재생성 forgen mcp list # 설치된 MCP 서버 목록 forgen mcp add <이름> # 템플릿에서 MCP 서버 추가 forgen mcp templates # 사용 가능한 템플릿 목록 forgen notepad show # 세션 노트패드 보기 forgen uninstall # forgen 깔끔하게 제거 ``` ### MCP 도구 (세션 중 Claude가 사용) | 도구 | 용도 | |------|------| | `compound-search` | 축적된 지식을 쿼리로 검색 (TF-IDF + BM25 + bigram 앙상블) | | `compound-read` | 솔루션 전문 읽기 (Progressive Disclosure Tier 3) | | `compound-list` | 상태/유형/범위 필터가 있는 솔루션 목록 | | `compound-stats` | 상태, 유형, 범위별 통계 현황 | | `session-search` | 이전 세션 대화 검색 (SQLite FTS5, Node.js 22+) | | `correction-record` | 사용자 교정을 구조화된 evidence로 기록 | | `profile-read` | 현재 개인화 프로필 읽기 | | `rule-list` | 카테고리별 활성 개인화 규칙 목록 | --- ## 아키텍처 ``` ~/.forgen/ 개인화 홈 |-- me/ | |-- forge-profile.json 4축 프로필 (팩 + facet + trust) | |-- rules/ 규칙 저장소 (규칙별 JSON 파일) | |-- behavior/ Evidence 저장소 (교정 + 관찰) | |-- recommendations/ 팩 추천 (온보딩 + mismatch) | +-- solutions/ Compound 지식 |-- state/ | |-- sessions/ 세션 상태 스냅샷 | +-- raw-logs/ Raw 세션 로그 (7일 TTL 자동 정리) +-- config.json 글로벌 설정 (locale, trust, packs) ~/.claude/ |-- settings.json 훅 + 환경변수 (하네스가 주입) |-- rules/ | |-- forge-behavioral.md 학습된 행동 패턴 (자동 생성) | +-- v1-rules.md 렌더링된 개인화 규칙 (세션별) |-- commands/forgen/ 슬래시 커맨드 (승격된 스킬) +-- .claude.json MCP 서버 등록 ~/.compound/ 레거시 compound 홈 (훅/MCP가 아직 참조) |-- me/ | |-- solutions/ 축적된 compound 지식 | |-- behavior/ 행동 패턴 | +-- skills/ 승격된 스킬 +-- sessions.db SQLite 세션 이력 (Node.js 22+) ``` ### 데이터 흐름 ``` forge-profile.json 개인화의 단일 진실 원천 | v preset-manager.ts 세션 상태 합성: 글로벌 안전 규칙 hard constraint (항상 활성) + 기본 팩 규칙 프로필 팩에서 + 개인 오버레이 교정 생성 규칙에서 + 세션 오버레이 현재 세션 임시 규칙 + 런타임 능력 감지 trust 정책 조정 | v rule-renderer.ts Rule[]을 자연어로 변환: 필터 (active만) 파이프라인: filter -> dedupe -> group -> dedupe (render_key) order -> template -> budget (4000자) 카테고리별 그룹 순서: Must Not -> Working Defaults -> When To Ask -> How To Validate -> How To Report | v ~/.claude/rules/v1-rules.md Claude가 실제로 읽는 파일 ``` --- ## 안전 안전 훅은 `settings.json`에 자동 등록되며, Claude의 모든 도구 호출 시 실행됩니다. | 훅 | 트리거 | 기능 | |----|--------|------| | **pre-tool-use** | 모든 도구 실행 전 | `rm -rf`, `curl\|sh`, `--force` push, 위험 패턴 차단 | | **db-guard** | SQL 연산 | `DROP TABLE`, `WHERE` 없는 `DELETE`, `TRUNCATE` 차단 | | **secret-filter** | 파일 쓰기, 출력 | API 키, 토큰, 자격 증명 노출 시 경고 | | **slop-detector** | 코드 생성 후 | TODO 잔재, `eslint-disable`, `as any`, `@ts-ignore`, 빈 catch 감지 | | **prompt-injection-filter** | 모든 입력 | 패턴 + 휴리스틱 기반 프롬프트 인젝션 차단 | | **context-guard** | 세션 중 | 50 프롬프트/20만 자 시 경고, 12만 자 자동 압축, 세션 인계 | | **rate-limiter** | MCP 도구 호출 | 과도한 MCP 도구 호출 방지 | | **drift-detector** | 파일 편집 | EWMA 기반 drift 점수: 경고 → 위험 → 50회 편집 시 강제 정지 | | **agent-validator** | 에이전트 도구 출력 | 서브 에이전트 출력이 비어있거나 실패/잘린 경우 경고 | 안전 규칙은 **hard constraint**입니다 -- 팩 선택이나 교정으로 재정의할 수 없습니다. 렌더링된 규칙의 "Must Not" 섹션은 프로필과 무관하게 항상 존재합니다. --- ## 핵심 설계 원칙 - **4축 프로필, 선호도 토글이 아님.** 각 축에는 팩(대분류)과 facet(0-1 수치의 세밀한 조정)이 있습니다. 팩은 안정적 행동을 제공하고, facet은 전체 재분류 없이 미세 조정을 가능하게 합니다. - **Evidence 기반 학습, regex 매칭이 아님.** 교정은 구조화된 데이터(`CorrectionRequest`: kind, axis_hint, message)입니다. Claude가 분류하고, 알고리즘이 적용합니다. 사용자 입력에 대한 패턴 매칭이 없습니다. - **Pack + overlay 모델.** 기본 팩이 안정적 기본값을 제공합니다. 교정에서 생성된 개인 오버레이가 위에 쌓입니다. 세션 오버레이는 임시 규칙입니다. 충돌 해소: 세션 > 개인 > 팩 (글로벌 안전은 항상 hard constraint). - **자연어로 렌더링된 규칙.** `v1-rules.md` 파일에는 설정이 아닌 한국어(또는 영어) 문장이 담깁니다. Claude는 "동작하는 코드를 불필요하게 리팩토링하지 마라"같은 지침을 읽습니다 -- 사람 멘토가 가이드를 주는 것과 같은 방식입니다. - **Mismatch 감지.** 최근 3세션 rolling 분석으로 교정이 지속적으로 현재 팩과 다른 방향을 가리키는지 확인합니다. 감지되면 조용히 drift하지 않고, 팩 재추천을 제안합니다. - **런타임 trust 계산.** 원하는 trust 정책이 Claude Code의 실제 런타임 권한 모드와 조율됩니다. Claude Code가 `--dangerously-skip-permissions`로 실행되면, forgen가 effective trust 수준을 그에 맞게 조정합니다. - **국제화.** 영어와 한국어 완전 지원. 온보딩 시 언어를 선택하면 온보딩 질문, 렌더링된 규칙, CLI 출력 전체에 적용됩니다. --- ## 공존 forgen는 설치 시 다른 Claude Code 플러그인(oh-my-claudecode, superpowers, claude-mem)을 감지하고 컨텍스트 주입을 50% 자동 축소합니다 (양보 원칙). 핵심 안전 훅과 compound 훅은 항상 활성 상태를 유지합니다. 다른 플러그인이 이미 제공하는 스킬은 충돌을 피하기 위해 건너뜁니다. 자세한 내용은 [공존 가이드](docs/guides/with-omc.md)를 참고하세요. --- ## 문서 | 문서 | 설명 | |------|------| | [훅 레퍼런스](docs/reference/hooks-reference.md) | 3개 계층의 19개 훅 — 이벤트, 타임아웃, 동작 | | [공존 가이드](docs/guides/with-omc.md) | oh-my-claudecode와 forgen 함께 사용하기 | | [CHANGELOG](CHANGELOG.md) | 버전 히스토리 및 릴리즈 노트 | --- ## 라이선스 MIT