Filip-Podstavec/claude-leverage

모든 저장소(repo)를 AI-first로 만드세요 - 시작부터 지속 가능한 코드를 작성하거나, 레거시 코드베이스를 리팩터링하여 에이전트 주도 개발(agent-driven development)을 위한 준비를 마치세요.

컨벤션 레이어(Convention layer, AGENTS.md)는 Cursor, Windsurf, Copilot 등 AGENTS.md를 인식하는 모든 도구에 의해 읽힙니다.

Claude Code 및 Codex CLI를 위한 작고 주관이 뚜렷한 AI 코딩 에이전트(AI-coding-agent) 스위트: 결정론적 보안 후크(deterministic security hooks), 도구 간 스킬(cross-tool skills), 그리고 다음 에이전트가 저장소를 안전하게 수정할 수 있도록 유지해 주는 자가 유지 컨벤션(self-maintaining conventions)을 제공합니다.

공식 superpowers 플러그인과 같은 스킬 기반 플러그인을 보완하며, 이를 대체하려고 시도하지 않습니다.

• 해결하는 문제
• 대상 사용자
• 빠른 시작 (Quick start)
• 설치 (Install)
• 제공 기능
• 작동 방식
• 벤치마크 (Benchmarks)
• 비교 분석
• 내부 구성 요소
• 왜 두 도구를 위해 하나의 저장소를 사용하는가
• 솔직한 역사
• 검증, 업데이트, 삭제
• 라이선스 (License)

AI 에이전트와 함께 빠른 속도로 결과물을 내놓는 것은 쉽습니다. 하지만 6개월 뒤에 이 저장소를 여는 다음 에이전트(사람 또는 AI)가 여전히 안전하게 수정할 수 있는 방식으로 결과물을 내놓는 것이 어려운 부분입니다. 여기서 제공하는 후크(hooks), 컨벤션(conventions), 스킬(skills)은 단순히 세션 시작 시점에만 작동하는 것이 아니라, 저장소가 성장함에 따라 지속적으로 작동하며 이 두 번째 과제를 자동화합니다.

스택이 없는 경우	claude-leverage 사용 시
세션 간에 컨텍스트(Context)가 소멸되어, 모든 에이전트가 저장소를 처음부터 다시 학습해야 합니다.	AIDEV 앵커(anchors)와 context-surface 후크가 편집 시점에 적절한 사실들을 드러냅니다.
문서가 코드와 동기화되지 않고 어긋나다가 결국 아무도 믿지 않게 됩니다.	자가 유지(Self-maintenance) 알림이 누락된 AGENTS.md, 오래된 앵커, 코드와 문서 간의 불일치를 수정 비용이 저렴할 때 바로 찾아냅니다.
큰 작업들은 맥락을 놓치며, 결정 뒤에 숨겨진 이유(why)가 증발합니다.	지속 가능한 메모리(Durable memory): ADR(Architecture Decision Records)과 정제된 세션 로그가 세션 전반에 걸쳐 의도를 전달합니다.
부주의한 에이전트와 유출된 비밀(secret) 또는 강제 푸시(force-push) 사이를 막아줄 것이 아무것도 없습니다.	결정론적 셸 후크(Deterministic shell hooks)가 모델의 결정이 내려지기 전에 비밀 정보, 강제 푸시, --no-verify를 차단합니다.

이 저장소의 모든 결정은 세 가지 속성을 따릅니다:

기본 설정된 보안 (Security by default) - 결정론적 훅 (deterministic hooks)을 사용하며, 모델이 필요하지 않습니다.
저장소가 성장함에 따라 스스로 유지 관리 (Self-maintaining as the repo grows) - 비차단형(non-blocking) 넛지(nudge)가 유지 관리 부채를 조기에 드러냅니다.
설계 단계부터 도구 간 호환 (Cross-tool by design) - 동일한 AGENTS.md, 동일한 SKILL.md, 그리고 Claude Code와 Codex에서 동일한 훅 스크립트를 사용합니다. 한 번만 작성하면 됩니다.

클라이언트 저장소에서 작업하는 프리랜서 - 에이전트를 통해 여러 클라이언트의 코드베이스에 걸쳐 기능을 배포하며, 각 코드베이스는 반환 시 안전한 상태를 유지해야 합니다. 보안 훅과 AGENTS.md 컨벤션이 여러분과 함께 이동합니다.
레거시 저장소를 물려받은 팀 - 문서가 없는 6개월 된 코드베이스를 열었습니다. /repo-doctor가 AI 준비도 (AI-readiness)를 점수화하고 가장 영향력이 큰 격차를 지목합니다. 부트스트랩 기술 (bootstrap skills) 덕분에 빠르게 탐색할 수 있습니다.
빠른 속도로 배포하는 1인 개발자 - 저장소가 유지 관리 불가능한 AI 슬롭 (AI-slop)으로 부패하지 않으면서도 속도를 유지하고 싶습니다. 자가 유지 관리 넛지와 ADR/세션 메모리가 의도를 온전하게 유지해 줍니다.

저장소를 물려받았거나 이미 보유하고 있나요? 여기서 시작하세요. 플러그인을 설치합니다:

/plugin marketplace add Filip-Podstavec/claude-leverage
/plugin install claude-leverage@filip-podstavec

그 다음, 하향식 (top-down)으로 저장소를 AI 준비 상태로 만드세요:

• 읽기 전용 AI 준비도 감사 (AI-readiness audit). 약 20가지 차원 (Foundation / Why / What / In-code / Hygiene / Sync)을 점수화하고 가장 중요한 격차를 지목합니다. /repo-doctor
• 보고된 상위 격차를 수정하세요 - 보통 /init-repo (루트에 AGENTS.md 삽입)를 수행한 다음, 기계 판독 가능한 모듈 메타데이터와 도메인 용어를 위해 /arch-map 및 /glossary-init을 실행합니다.
• 편집 시점에 적절한 앵커 (anchors)가 나타날 수 있도록, 적시 컨텍스트 노출 (just-in-time context surfacing)을 지원하는 매니페스트 (manifest)를 구축합니다. /refresh-context-map

새 저장소를 시작하시나요? 설치 후 /init-repo를 실행하여 AGENTS.md, .gitignore 패턴 및 선택 사항인 구조화된 로깅 (structured-logging) 스타터를 삽입하세요.

전체 설치 방법 (Codex CLI 포함)은 아래와 같습니다.

/plugin marketplace add Filip-Podstavec/claude-leverage
/plugin install claude-leverage@filip-podstavec

끝입니다. Claude Code를 재시작하세요 (또는 /skill list 및 /agents를 실행하세요).

(현재 세션에서) 14개의 모든 기술 (skills)과 2개의 서브 에이전트 (subagents)를 불러오기 위해.

Codex는 플러그인 마켓플레이스가 없으므로, 스크립트를 통해 설치합니다:

# 1. Codex CLI 자체를 설치 (1회성)
npm i -g @openai/codex
# 2. 이 저장소(repo)를 안정적인 위치로 클론(Clone)
...

Codex 설치 프로그램이 수행하는 작업

• 저장소 경로를 ~/.codex/hooks.json으로 해결(Resolves)하여, 모든 Codex 세션에서 전역적으로 보안 + 넛지 (nudge) 훅 (hooks)이 실행되도록 합니다.
• @<repo-path>/AGENTS.md를 ~/.codex/AGENTS.md에 추가하여, 모든 Codex 세션에서 표준 가이드라인 (canonical guidance)이 로드되도록 합니다.
• .codex/agents/*.toml을 ~/.codex/agents/로 복사합니다.
• 14개의 모든 기술 (skills)을 ~/.agents/skills/claude-leverage/로 복사하여, Claude Code에서와 정확히 동일하게 Codex 세션에서 작동하도록 합니다.

멱등성 (Idempotent): 재실행 시 마커 주석 (marker comments)을 통해 기존 설치를 감지하고 제자리에서 덮어씁니다. 원자적 기술 교체 (Atomic skill swap, 스테이징 디렉토리 + 이름 변경 방식)를 사용하여, 루프 중간에 복사가 실패하더라도 이전 설치 상태를 온전하게 유지합니다.

왼쪽에서 오른쪽으로 5개의 세그먼트가 표시됩니다: 5시간 속도 제한 (rate limit), 7일 속도 제한, 현재 컨텍스트 윈도우 (context window) %, 모델 이름, git 브랜치.

Claude-Code 전용 (Codex에는 상태 표시줄 (statusline)이 없습니다). 단일 Python 파일로 구성되며, jq 의존성 없이 Git Bash 환경의 Windows에서 작동합니다. 색상 임계값 (Color thresholds): 초록색 <60 %, 노란색 60-84 %, 빨간색 ≥85 %.

# ~/.claude/ 로 복사 (상태 표시줄이 구성되어 있지 않은 경우에만 덮어씁니다)
cp statusline/statusline-command.sh ~/.claude/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

그 다음 ~/.claude/settings.json에 추가합니다:

"statusLine": {
"type": "command",
"command": "bash ~/.claude/statusline-command.sh"
...

Claude Code를 재시작하세요. 나중에 사용을 중단하려면 settings.json에서 statusLine 블록을 삭제하세요.

항상 작동하는 안전 장치 (Always-on safety) - 훅 (hooks), 설정 불필요, 모델 호출 없음

block-secrets-precommit - 스테이징된 차이점 (diff)에 API 키 / 토큰 / 개인 키가 포함되어 있으면 git commit을 거부합니다 (마커 주석을 통한 라인별 허용 목록 지원).

block-dangerous-git - 보호된 브랜치 (protected branches)에서 git push --force, --no-verify, git reset --hard를 거부합니다.

ai-first-nudge

• non-blocking (비차단): 테스트 파일이 아닌 파일에서 AIDEV-NOTE 없이 ≥50 net-new LOC(순 신규 코드 라인 수) 발생 OR AGENTS.md가 없는 새로운 소스 디렉토리(source-dir) 생성 → 한 줄 제안 security-nudge

• non-blocking (비차단) Stop hook: 민감한 경로(sensitive paths)를 수정하는 ≥80 net-new LOC 발생 → /security-review 제안

stack-freshness

• non-blocking (비차단) SessionStart: 마지막 /stack-check 이후 30일 이상 경과

→ SessionStart additionalContext를 통한 한 줄 리마인더

(no network) bare-repo-nudge

• non-blocking (비차단) SessionStart, 두 브랜치(two-branch) nudge: (A) 현재 작업 디렉토리(cwd)가 git 리포지토리가 아니며 $HOME, /, /tmp, /system도 아닌 경우 → git init + /init-repo를 수행하도록 리마인더; (B) cwd가 git 리포지토리이지만 루트에 AGENTS.md 또는 CLAUDE.md가 없고 프로젝트 마커 파일(package.json, pyproject.toml, Cargo.toml, go.mod, ...)은 있는 경우 → 컨벤션 레이어(AIDEV anchors, 구조화된 로깅 등)가 실제로 로드될 수 있도록 /init-repo를 수행하도록 리마인더. cwd/리포지토리 루트당 하루에 한 번 실행.

skill-cheatsheet

• non-blocking (비차단) SessionStart, 리포지토리의 AGENTS.md에 claude-leverage: 마커가 있는 경우에만 제한적으로 실행 (즉, 사용자가 스택을 능동적으로 채택한 경우). SessionStart additionalContext를 통해 리포지토리당 14일에 한 번 고가치 기술(high-value skills) + 트리거의 압축된 목록을 노출. 문서화된 기술 자동 활성화 격차(skill-auto-activation gap, 런타임이 첫 줄만 파싱하는 description: | 블록 스칼라 문제)를 완화함. CLAUDE_LEVERAGE_SKILL_HINT_DAYS를 통해 재정의 가능 (0 = 비활성화).

context-surface

• opt-in (선택 사항) Read|Edit|Write|MultiEdit에 대한 PreToolUse hook. .claude-leverage-context-map.json에 있는 미리 구축된 매니페스트(manifest)를 읽고 (scripts/build-context-map.py 또는 /refresh-context-map 스킬에 의해 생성됨), 에이전트가 수정하려는 파일에 적용되는 AIDEV anchors를 hookSpecificOutput.additionalContext를 통해 방출함. 세션당 토큰 비용(token tax)을 절감함 - 에이전트가 문서화된 주의사항(gotchas)을 파악하기 위해 모든 AGENTS.md를 선제적으로 읽을 필요가 없음; 수정하는 순간에 적절한 anchors가 노출됨. 매니페스트가 없는 경우 유연하게 아무 작업도 수행하지 않음(no-op). 상세 모드(CLUID_LEVERAGE_CTX_VERBOSE=1)는 디렉토리별 AGENTS.md도 방출함.

chain- ADR 참조. 옵트아웃(Opt-out):
CLAUDE_LEVERAGE_CTX_DISABLE=1

. ADR 0008 참조.

• ADR 참조. 옵트아웃(Opt-out):

보안 검토 (Security review) - 기술 + 전용 서브에이전트 (subagent)

/security-review

• OWASP-Top-10 형태의 이슈 및 package.json, /requirements.txt에 대한 현재 차이점(diff) 감사(audit).

타이포스쿼팅(typosquatting) 휴리스틱.
읽기 전용(Read-only) Sonnet 서브에이전트가 file:line 형식을 포함한 Critical / Important / Nice 스키마를 반환함.

다른 플러그인에 대한 의존성 없음.

저장소 유지보수 기술 (Repo-maintenance skills) - 주기적으로 호출

/repo-map

• 멱등성(idempotent) 마커 사이의 README 내 아키텍처 Mermaid 블록을 새로고침함; madge 또는 /pydeps를 통한 선택적 의존성 그래프(dep-graph) 블록 생성.

/process-diagram <name>

• 지정된 워크플로우에 대한 시퀀스/플로우차트(sequence/flowchart)를 생성하여 대상 마크다운의 마커 사이에 삽입하며, mmdc로 검증됨.

/stack-check

• stack.toml 대비 Claude Code + Codex + 플러그인 + CLI 의존성 버전 확인, 그리고 오래된 앵커(stale-anchor) 탐색 + AGENTS.md 무결성 감사 수행.

/log-structured

• 비구조화된 로깅(non-structured logging)을 감사하고, JSON-lines 컨벤션에 따라 규격에 맞는 대체 방안을 제안함.

설정 및 핸드오프 기술 (Setup & handoff skills) - 프로젝트별 / 결정별

/init-repo

• 새로운 프로젝트 부트스트랩(bootstrap): 언어별 템플릿으로부터 AGENTS.md 생성, .gitignore 패턴 적용, 선택적 구조화된 로깅(structured-logging) 스타터 /codex-sandbox 제공.

• 프로젝트별 .codex/config.toml 설정, 샌드박스(sandbox) + 승인 모드(dev / prod / custom) 구성.

/explain-diff

• 세 가지 대상 모드(--for pr / review / self)에 따라 3~5개의 불렛 포인트로 구성된 쉬운 영어 차이점(diff) 설명.

/adr-new

• 번호가 매겨진 MADR 스타일의 아키텍처 결정 기록(Architecture Decision Record, ADR) 부트스트랩. 상태는 불변(Immutable)이며, 6개월 후의 다음 에이전트를 위해 *이유(why)*를 기록함.

/session-log

• 현재 세션을 docs/sessions/로 요약. 세션 간의 연속성 계층 역할을 하며, 전체 기록(transcript)이 아닌 정수(distillate)를 생성함.

/glossary-init

• 이 저장소에 특화된 도메인 용어를 위해 저장소 루트의 GLOSSARY.md를 부트스트랩/확장함. 식별자 빈도에 따라 후보를 노출하며, 정의를 절대 임의로 만들어내지 않음(사용자가 직접 입력함).

/arch-map

• architecture.yml 부트스트랩/새로고침

저장소 루트(repo root)에 위치 - 기계 판독 가능한 모듈 메타데이터 (역할/안정성/공개 인터페이스(public_surface)/...); 수동 관리됨.

--validate 모드는 CI용

/repo-doctor

• 읽기 전용 AI 준비성 감사(AI-readiness audit). 기반(Foundation) (AGENTS.md, CLAUDE.md, 디렉토리별 AGENTS.md), 이유(Why) (ADRs, 세션 로그), 내용(What) (GLOSSARY.md, architecture.yml), 코드 내(In-code) (AIDEV 앵커 밀도, 기한 초과), 위생(Hygiene) (테스트 + 테스트/소스 LOC 비율, 구조화된 로깅, .gitignore, README 퀵스타트, 언어 매니페스트), 그리고 동기화(Sync) (코드↔문서 드리프트: arch-map 대 디스크, 용어집(glossary) 대 코드, 디렉토리별 AGENTS.md 노후화, CHANGELOG 대 버전, README 슬래시 참조(slash-refs)) 등 약 20개 차원을 점수화함. 각 격차(gap)는 구체적인 수정 조치(fix action)로 연결됨.

--score

/--json

/--fail-on missing|todo|stale

/--scope foundation|why|what|hygiene|sync|all

CI 게이팅(gating)용

/refresh-context-map

• .claude-leverage-context-map.json 재구축. 이는 context-surface PreToolUse 훅을 구동하는 매니페스트(manifest)임. 앵커(anchor) / 디렉토리별 AGENTS.md / ADR 변경 후, 또는 git merge 후에 실행하십시오. (.gitattributes merge=ours를 통해 매니페스트가 로컬로 자동 해결되지만, 재구축 전까지는 병합된 트리와 비교하여 노후화된 상태가 됨)

워크플로우 명령(Workflow commands) - Claude Code 전용

/flaky-test

• N회 실행 안정성 분석을 위해 flaky-test-isolator 서브 에이전트(subagent)에 위임

(커밋의 경우, 기본 Claude 커밋 워크플로우와 block-secrets-precommit / block-dangerous-git 훅이 이미 비밀번호 스캐닝, Conventional Commits 스타일, .env 거부, --no-verify 거부, 강제 푸시(force-push) 거부를 처리합니다. v1.4.4에서 /commit-smart 슬래시 명령어를 제거했습니다. 이는 선택 사항(opt-in)이어야 할 작업에 위험한 자동 푸시를 추가했기 때문입니다. 그냥 기본 방식으로 커밋하고, 원할 때 명시적으로 푸시하십시오.)

컨벤션(Conventions) - 문서 및 유도(nudges)를 통해 강제됨

• AIDEV-NOTE / AIDEV-TODO / AIDEV-QUESTION 앵커 주석 (선택 사항인 ISO-8601 마감일 포함 가능: AIDEV-TODO(by: 2026-08-01))

• trace_id / span_id / attrs를 포함하는 JSON-lines 구조화된 로깅 사양

• 복잡한 모듈을 위한 디렉토리별 AGENTS.md

• 핵심적인 아키텍처 결정 사항을 위한 ADRs (Architecture Decision Records)

• AI 세션 간의 연속성을 위한 세션 로그 (Session logs)

도구 간 연결 (Cross-tool plumbing)

• Claude Code (CLAUDE.md 내 @AGENTS.md 임포트를 통해) 및 Codex (네이티브 읽기)를 위한 동일한 AGENTS.md 사용
• 두 도구가 공유하는 scripts/hooks/ 내의 훅 스크립트 (Hook scripts)
• Codex 설치 프로그램에 의해 ~/.agents/skills/에 설치되는 스킬 (Skills)
• MD로 작성되고 Codex와의 일관성을 위해 TOML로 자동 생성되는 서브에이전트 (Subagents) (CI 게이트 적용)

보안에 민감한 기능을 위한 전형적인 엔드 투 엔드 (end-to-end) 세션:

sequenceDiagram
autonumber
actor User
...

다이어그램 읽기: 명시적인 사용자 호출은 실선 화살표 (User -> CC), 자동 훅 실행은 점선인 Hook -> User 반환, 서브에이전트 위임은 하나의 Task입니다.