Claude on philipjkim

Agentic Coding 시대의 Repo 부트스트래핑 가이드 Part 1: AGENTS.md 와 spec 문서 지형도

Thu, 28 May 2026 19:02:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

들어가며: README 한 장으로 안 되는 시대

신규 서비스를 위한 git repo 를 막 만들었다고 합시다. 2년 전이라면 README.md 한 장에 빌드 명령과 디렉터리 구조를 적고, 나머지는 코드와 머릿속에서 합의된 관행으로 굴러갔습니다. 새 팀원이 들어오면 옆 자리 동료가 30분쯤 설명해 주고, 그걸로 충분했습니다.

지금은 그 “옆 자리 동료” 역할의 절반 이상을 Claude Code, Codex CLI, Gemini CLI, Cursor 같은 에이전트가 맡고 있습니다. 그런데 에이전트는 옆 자리에 앉지 않습니다. 매 세션마다 처음 합류한 신입처럼 repo 에 들어와서, 우리가 적어 둔 텍스트만 읽고 일을 시작합니다. 에이전트에게 “이 프로젝트는 이런 곳이고, 이런 규칙으로 일한다” 를 전달하는 문서가 부실하면, 에이전트가 만드는 결과물의 품질은 운에 좌우됩니다.

Superpowers 플러그인 가이드 Part 4: 명시 호출 vs 자동 트리거 — 실전 가이드와 한계

Wed, 20 May 2026 16:58:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

1편 에서 개요와 설치를, 2편 에서 핵심 워크플로우를, 3편 에서 품질 보증 스킬을 다뤘습니다. 마지막 4편에서는 실전에서 가장 자주 부딪히는 질문에 답합니다.

“이거 그냥 두면 알아서 다 해주는 건가요, 아니면 매번 /superpowers:xxx 로 호출해야 하나요?”

답은 “대부분 자동이지만, 의도적으로 명시 호출해야 더 잘 작동하는 케이스가 있다” 입니다. 이 글에서는 두 모드의 비교 분석, 트러블슈팅, 커스터마이즈 방법, 그리고 Java/Go 백엔드 개발 현장에서의 실용 팁과 한계를 정리합니다.

Superpowers 플러그인 가이드 Part 3: 품질 보증 스킬 — TDD, Systematic Debugging, Verification, Code Review

Wed, 20 May 2026 16:57:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

1편 에서 Superpowers 의 개요와 설치를, 2편 에서 핵심 워크플로우를 다뤘습니다. 3편은 그 워크플로우 안에서 작동하면서 에이전트의 합리화와 빠져나갈 구멍을 차단 하는 품질 보증 스킬들을 자세히 들여다봅니다.

이 스킬들은 모두 “Iron Law” 라는 이름의 명문화된 규칙을 갖고 있다는 공통점이 있습니다. 그리고 각 스킬의 문서 안에는 “Red Flags” 표 가 들어 있어, 에이전트가 빠져나가려 할 때 흔히 하는 합리화의 패턴들을 그대로 박아두었습니다. 이게 결과적으로 모델의 행동을 바꿉니다.

Superpowers 플러그인 가이드 Part 2: 핵심 워크플로우 — Brainstorming부터 Subagent-driven Development까지

Wed, 20 May 2026 16:56:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

1편 에서는 Superpowers 가 무엇이고 어떻게 자동 트리거되는지를 다뤘습니다. 2편은 가장 핵심이라고 할 수 있는 개발 워크플로우 전체 를 깊게 들여다봅니다.

전체 흐름은 다음과 같습니다.

flowchart LR
 A[brainstorming] --> B[using-git-worktrees]
 B --> C[writing-plans]
 C --> D{독립 태스크?}
 D -->|yes| E[subagent-driven-development]
 D -->|no/사람 체크포인트 선호| F[executing-plans]
 E --> G[finishing-a-development-branch]
 F --> G

 style A fill:#90EE90,color:#000000
 style B fill:#87CEEB,color:#000000
 style C fill:#FFD700,color:#000000
 style D fill:#FFB6C1,color:#000000
 style E fill:#DDA0DD,color:#000000
 style F fill:#DDA0DD,color:#000000
 style G fill:#FFA07A,color:#000000

이 글에서는 각 스킬이 실제로 무엇을 하는지, 그리고 Go 기반 백엔드 서비스에 새 API 엔드포인트를 추가 하는 시나리오를 따라가며 흐름을 체험해 봅니다.

Superpowers 플러그인 가이드 Part 1: 소개, 설치, 그리고 철학

Wed, 20 May 2026 16:55:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

들어가며

Claude Code, Codex CLI, Cursor 등 코딩 에이전트(coding agent)를 매일 쓰는 백엔드 개발자라면 한 번쯤은 이런 경험이 있을 겁니다. “간단한 기능 하나만 추가해줘” 라고 했더니, 요구사항 정리 없이 코드를 우다다 쏟아내다가 절반쯤에서 길을 잃고, 테스트도 빠진 채 “완료했습니다” 라고 보고하는 경우 말입니다. 모델은 똑똑한데, 작업 방식이 들쭉날쭉해서 결과의 품질이 운에 좌우됩니다.

Jesse Vincent 가 만든 Superpowers 는 바로 이 지점을 노린 플러그인입니다. 모델을 더 똑똑하게 만드는 게 아니라, 모델이 언제, 어떤 순서로, 어떤 규율로 일해야 하는지를 강제하는 “방법론(methodology)” 자체를 플러그인 형태로 주입합니다.

AI 시대 엔지니어의 심화 전략: 복리 게임, 거울의 한계, 선제적 AI 활용

Wed, 25 Feb 2026 13:54:39 +0900

이 글은 Claude Opus 4.6 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.
이 글의 시작이 된 에세이: 코드를 읽지 않는 시대, 엔지니어는 무엇을 읽어야 하는가

1. 복리 게임: 정의, 본질, 그리고 승리 전략

복리 게임이란 무엇인가

Kent Beck이 제시한 복리 게임(The Compounding Game) 은 소프트웨어 개발의 본질을 설명하는 프레임이다. 이를 이해하려면 먼저 그 반대편에 있는 결승선 게임과 대비해야 한다.

결승선 게임(The Finish Line Game) 은 명확한 종료 조건이 있는 게임이다. “X를 하는 소프트웨어가 필요하다 → X를 구현하면 끝.” 일회성 스크립트, PoC, 해커톤 프로젝트가 여기에 해당한다. 가장 빠르게 결승선에 도달하는 사람이 이기고, 결승선을 넘으면 게임이 끝난다. AI 바이브 코딩이 압도적으로 유리한 영역이기도 하다.

Claude Code Compaction 가이드

Wed, 04 Feb 2026 19:28:33 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Claude Code를 하루 종일 사용하다 보면 어느 순간 “Compacting our conversation…” 메시지와 함께 작업 흐름이 끊기는 경험을 하게 됩니다. 이 글에서는 Compaction이 무엇인지, 왜 자주 발생하는지, 그리고 어떻게 줄일 수 있는지 실전 전략을 공유합니다.

Compaction이란?

Claude Code는 대화 내용, 읽은 파일, 명령어 출력 등을 Context Window라는 제한된 공간에 저장합니다. 이 공간이 가득 차면 Claude는 더 이상 새로운 정보를 처리할 수 없게 됩니다.

Claude Code 완전 정복 가이드 Part 6: 고급 패턴과 Best Practices

Fri, 23 Jan 2026 17:21:06 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 1시간 30분 난이도: ⭐⭐⭐⭐⭐ 사전 요구사항: Part 1-5 완료 Claude Code 버전: 2.1.x (Opus 4.5)

0. Claude Code 2.1 주요 신기능

본격적인 내용에 앞서, Claude Code 2.1에서 추가된 핵심 기능들을 정리합니다:

기능	설명
Session Teleportation	`/teleport`, `/remote-env`로 로컬↔클라우드 세션 이동
Hot Reload for Skills	Skills 수정 시 재시작 없이 즉시 반영
Setup Hook	`--init`, `--init-only`, `--maintenance` CLI 플래그용 훅
Task Management	의존성 추적이 포함된 태스크 관리 시스템
Language Output	`language` 설정으로 출력 언어 지정
Opus 4.5	Pro 사용자에게 Opus 4.5 모델 제공
respectGitignore	`@-mention` 파일 선택에서 gitignore 적용
showTurnDuration	턴 소요 시간 표시 설정

1. Hooks: 예외 없는 강제 자동화

1.1 CLAUDE.md vs Hooks의 근본적 차이

flowchart TB
 subgraph Comparison["CLAUDE.md vs Hooks"]
 direction TB

 subgraph Advisory["📄 CLAUDE.md = '권고' (Advisory)"]
 A1["'테스트를 실행해주세요'<br/>'린트를 돌려주세요'"]
 A2["→ Claude가 따를 수도 있고, 잊을 수도 있음<br/>→ 복잡한 대화에서 규칙이 희석될 수 있음"]
 end

 subgraph Enforcement["⚡ Hooks = '강제' (Enforcement)"]
 E1["파일 저장 시 → 자동으로 린트 실행<br/>대화 시작 시 → 자동으로 컨텍스트 로드"]
 E2["→ 예외 없이 항상 실행됨<br/>→ Claude의 판단과 무관하게 트리거"]
 end
 end

 style Advisory fill:#fff9c4,color:#000000
 style Enforcement fill:#c8e6c9,color:#000000
 style A1 fill:#fffde7,color:#000000
 style A2 fill:#ffecb3,color:#000000
 style E1 fill:#e8f5e9,color:#000000
 style E2 fill:#a5d6a7,color:#000000

1.2 Hooks 이벤트 종류

이벤트	트리거 시점	사용 예시
`PreToolUse`	도구 실행 직전	위험한 명령 차단, 로깅
`PostToolUse`	도구 실행 직후	린트 자동 실행, 검증
`Notification`	알림 발생 시	외부 시스템 연동
`Stop`	작업 완료/중단 시	정리 작업, 리포트
`Setup`	`--init`, `--init-only`, `--maintenance` 실행 시	저장소 초기화, 유지보수 (2.1+ 신규)

💡 Claude Code 2.1+ 변경사항:

Claude Code 완전 정복 가이드 Part 5: 나만의 Plugin Marketplace 만들기 - 팀/조직 확장

Fri, 23 Jan 2026 17:21:03 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 1시간 30분 난이도: ⭐⭐⭐⭐ 사전 요구사항: Part 1-4 완료, Git/GitHub 기본 지식 Claude Code 버전: 2.1.x

1. Plugin 구조 이해

1.1 Plugin 디렉토리 구조

💡 주의: 2026년 기준, marketplace.json에서 Skills를 로드하려면 skills 필드가 필수입니다. 이 필드가 없으면 Skills가 로드되지 않습니다.

my-plugin/
├── .claude-plugin/
│ └── plugin.json # 필수: 플러그인 메타데이터
├── skills/ # 선택: Skills
│ └── my-skill/
│ └── SKILL.md
├── commands/ # 선택: Slash Commands
│ └── my-command.md
├── agents/ # 선택: Subagents
│ └── my-agent.md
├── hooks/ # 선택: Hooks 설정
│ └── hooks.json
├── .mcp.json # 선택: MCP 서버 설정
└── README.md # 권장: 문서화

1.2 plugin.json 필수 필드

{
 "name": "my-awesome-plugin",
 "version": "1.0.0",
 "description": "플러그인 설명",
 "author": "Your Name",
 "homepage": "https://github.com/you/my-plugin"
}

1.3 plugin.json 전체 스키마

{
 "name": "my-awesome-plugin",
 "version": "1.0.0",
 "description": "이 플러그인이 무엇을 하는지 간단히 설명",
 "author": "Your Name <you@example.com>",
 "homepage": "https://github.com/you/my-plugin",
 "repository": {
 "type": "git",
 "url": "https://github.com/you/my-plugin.git"
 },
 "license": "MIT",
 "keywords": ["go", "testing", "conventions"],
 "engines": {
 "claude-code": ">=2.0.0"
 },
 "dependencies": {
 "plugins": ["other-plugin@marketplace"]
 }
}

2. 첫 번째 Plugin 만들기

2.1 시나리오

Java/Kotlin 개발팀을 위한 Plugin을 만들어봅시다. 다음을 포함합니다:

Claude Code 완전 정복 가이드 Part 4: Plugins & Marketplace - 재사용 가능한 확장 패키지

Fri, 23 Jan 2026 17:21:00 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 1시간 난이도: ⭐⭐⭐ 사전 요구사항: Part 1, 2, 3 완료 Claude Code 버전: 2.1.x (VSCode Native Plugin Management 지원)

1. Plugin이란 무엇인가?

1.1 Skills vs Commands vs Plugins vs Subagents 개념 정리

Claude Code의 확장 시스템은 여러 요소로 구성됩니다. 각각의 역할을 명확히 이해해야 합니다:

💡 Claude Code 2.1+ 업데이트:

VSCode Native Plugin Management: VS Code 확장에서 플러그인을 직접 탐색하고 관리할 수 있습니다.
Task Management System: 의존성 추적이 포함된 새로운 태스크 관리 시스템이 추가되었습니다.
Anthropic 공식 Marketplace: anthropics/claude-code 저장소에 공식 플러그인 마켓플레이스가 포함되어 있습니다.

flowchart TB
 subgraph ExtSystem["Claude Code 확장 시스템 전체 구조"]
 direction TB

 subgraph Components["구성 요소"]
 direction LR
 Skills["🧠 Skills"]
 Commands["⌨️ Commands"]
 Subagents["👨‍💼 Subagents"]
 Plugins["📦 Plugins"]
 end

 subgraph Features["특징"]
 direction LR
 SK_F["자동 호출<br/>참조 지식<br/><br/>'레시피북'"]
 CMD_F["수동 호출<br/>/command<br/><br/>'단축키'"]
 SA_F["위임 실행<br/>격리 컨텍스트<br/><br/>'전문가'"]
 PL_F["배포 패키지<br/>(컨테이너)<br/><br/>'도구상자'"]
 end

 Skills --> SK_F
 Commands --> CMD_F
 Subagents --> SA_F
 Plugins --> PL_F

 subgraph PluginContents["Plugin이 포함할 수 있는 것"]
 direction LR
 P_Skills["Skills"]
 P_Commands["Commands"]
 P_Subagent["Subagent"]
 P_Hooks["Hooks"]
 P_MCP["MCP"]
 end
 end

 style Skills fill:#c8e6c9,color:#000000
 style Commands fill:#bbdefb,color:#000000
 style Subagents fill:#fff9c4,color:#000000
 style Plugins fill:#ffccbc,color:#000000
 style SK_F fill:#e8f5e9,color:#000000
 style CMD_F fill:#e3f2fd,color:#000000
 style SA_F fill:#fffde7,color:#000000
 style PL_F fill:#fbe9e7,color:#000000
 style PluginContents fill:#f5f5f5,color:#000000

1.2 각 요소 상세 비교

요소	호출 방식	컨텍스트	주요 용도	저장 위치
Skills	자동 (description 매칭)	메인에 주입	참조 지식, 패턴	`.claude/skills/`
Commands	수동 (`/command`)	메인에서 실행	반복 작업 자동화	`.claude/commands/`
Subagents	명시적 위임	격리된 윈도우	독립적 작업 처리	`.claude/agents/`
Plugins	설치 후 내부 요소 사용	해당 없음	배포/공유 패키지	Marketplace
Hooks	이벤트 트리거	자동 실행	강제 자동화	`.claude/settings.json`
MCP	외부 도구 연결	도구로 사용	외부 시스템 통합	`.mcp.json`

1.3 Plugin이 해결하는 문제

flowchart TB
 subgraph Before["❌ Plugin 등장 이전"]
 Q["'팀원 A의 Claude Code 설정을<br/>팀원 B에게 공유하려면?'"]
 B1["1. Skills 폴더 복사<br/>2. Commands 폴더 복사<br/>3. Agents 폴더 복사<br/>4. 설정 파일 수정<br/>5. 버전 관리 별도<br/>6. 업데이트 수동 반영"]
 BR["→ 복잡하고 오류 발생 가능성 높음"]
 end

 subgraph After["✅ Plugin 등장 이후"]
 A1["/plugin marketplace add my-team/our-plugins"]
 A2["/plugin install our-coding-standards@our-plugins"]
 AR["→ 버전 관리, 자동 업데이트,<br/>의존성 해결 모두 자동"]
 end

 Before --> After

 style Before fill:#ffcdd2,color:#000000
 style After fill:#c8e6c9,color:#000000
 style Q fill:#ef9a9a,color:#000000
 style BR fill:#ef9a9a,color:#000000
 style A1 fill:#a5d6a7,color:#000000
 style A2 fill:#a5d6a7,color:#000000
 style AR fill:#a5d6a7,color:#000000

2. Marketplace 시스템 이해

2.1 Marketplace란?

Marketplace는 Plugin들의 카탈로그입니다. Plugin을 검색하고 설치할 수 있는 저장소입니다.

Claude Code 완전 정복 가이드 Part 3: Skills 시스템 - 온디맨드 전문가 활용하기

Fri, 23 Jan 2026 17:20:57 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 1시간 난이도: ⭐⭐⭐ 사전 요구사항: Part 1, 2 완료 Claude Code 버전: 2.1.x (Hot Reload 지원)

1. Skills란 무엇인가?

1.1 CLAUDE.md vs Skills의 핵심 차이

CLAUDE.md는 항상 로드되는 “기본 매뉴얼"입니다. 반면 Skills는 필요할 때만 로드되는 “전문 레시피북"입니다.

💡 Claude Code 2.1+ 새 기능: Hot Reload - Skills를 수정하면 Claude Code를 재시작하지 않아도 즉시 반영됩니다. ~/.claude/skills/ 또는 .claude/skills/ 디렉토리의 변경사항이 실시간으로 적용됩니다.

Claude Code 완전 정복 가이드 Part 2: CLAUDE.md 최적화 - 비대해지는 것을 막아라

Fri, 23 Jan 2026 17:20:54 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 45분 난이도: ⭐⭐ 사전 요구사항: Part 1 완료, CLAUDE.md 사용 경험 Claude Code 버전: 2.1.x

1. 왜 CLAUDE.md는 간결해야 하는가?

1.1 LLM의 Instruction-following 한계

연구에 따르면 프론티어 LLM도 약 150-200개의 지시사항만 일관되게 따를 수 있습니다. Claude Code의 시스템 프롬프트 자체가 이미 ~50개의 지시를 포함하고 있어, CLAUDE.md에 사용할 수 있는 “지시 예산"은 제한적입니다.

flowchart TB
 subgraph Capacity["LLM 지시 따르기 용량"]
 direction TB
 Title["📊 총 용량: ~150-200개 지시"]

 subgraph Components["구성 요소"]
 direction LR
 A["🤖 Claude Code<br/>시스템 프롬프트<br/>(~50개)"]
 B["📄 CLAUDE.md<br/><br/>(당신의 몫)"]
 C["🧠 Skills/Rules<br/><br/>(추가 지시)"]
 end

 Warning["⚠️ 초과 시 → 균일하게 모든 지시를 무시하기 시작"]
 end

 Title --> Components
 Components --> Warning

 style Title fill:#e3f2fd,color:#000000
 style A fill:#bbdefb,color:#000000
 style B fill:#c8e6c9,color:#000000
 style C fill:#fff9c4,color:#000000
 style Warning fill:#ffcdd2,color:#000000

1.2 토큰 비용과 Context Window

CLAUDE.md는 모든 대화에서 항상 로드됩니다. 파일이 커질수록:

Claude Code 완전 정복 가이드 Part 1: CLAUDE.md 기초 - 첫 발을 내딛다

Fri, 23 Jan 2026 17:20:51 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

예상 소요 시간: 30분 난이도: ⭐ 사전 요구사항: Claude Code 설치 완료 (v2.1.x)

1. Claude Code란 무엇인가?

1.1 Agentic Coding의 개념

Claude Code는 단순한 코드 자동완성 도구가 아닙니다. Agentic Coding Assistant로서, 터미널에서 직접 코드베이스를 읽고, 파일을 생성/수정하고, 테스트를 실행하고, Git 작업까지 수행할 수 있습니다. 2025년 2월 첫 출시 이후 빠르게 발전하여, 현재 버전 2.1.x에서는 Opus 4.5 모델을 지원하며 더욱 강력한 기능을 제공합니다.

Claude Code 완전 정복 가이드 Part 0: Overview

Fri, 23 Jan 2026 17:20:48 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

버전: 2026년 1월 기준 (Claude Code 2.1.17 / Opus 4.5)
대상 독자: Claude Code를 처음 시작하거나, 이미 사용 중이지만 더 효율적으로 활용하고 싶은 개발자

🎯 이 가이드의 목표

이 가이드는 Claude Code 초보 사용자가 CLAUDE.md 파일 하나 만드는 것에서 시작해서, Skills와 Plugins를 활용한 고급 워크플로우까지 단계별로 성장할 수 있도록 구성되어 있습니다.

flowchart TD
 A["📝 CLAUDE.md<br/>생성"] --> B["⚡ 최적화<br/>전략"]
 B --> C["🧠 Skills<br/>분리"]
 C --> D["🔌 Plugins<br/>활용"]
 D --> E["🏪 Marketplace<br/>구축"]
 E --> F["🎯 고급 패턴<br/>통합"]
 
 style A fill:#bbdefb,color:#000000
 style B fill:#c8e6c9,color:#000000
 style C fill:#fff9c4,color:#000000
 style D fill:#ffccbc,color:#000000
 style E fill:#d1c4e9,color:#000000
 style F fill:#f8bbd0,color:#000000

📚 가이드 구성

Part 1: CLAUDE.md 기초 - 첫 발을 내딛다

예상 소요 시간: 30분 | 난이도: ⭐