# Claude Code를 일상 도구로 쓰기: Claude.md, Skills, Subagents, Plugins, MCP

> Clean Markdown view of GeekNews topic #29957. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=29957](https://news.hada.io/topic?id=29957)
- GeekNews Markdown: [https://news.hada.io/topic/29957.md](https://news.hada.io/topic/29957.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-05-28T23:04:41+09:00
- Updated: 2026-05-28T23:04:41+09:00
- Original source: [arps18.github.io](https://arps18.github.io/posts/claude-code-mastery/)
- Points: 1
- Comments: 1

## Topic Body

- **Claude Code** 생산성은 프롬프트보다 메모리, 커스텀 명령, 병렬 세션, 프로젝트 설정을 누적하고 검증하는 방식에서 크게 갈림
- `CLAUDE.md`는 짧고 검증 중심인 **누적 인프라**로 운영해야 하며, 실수 뒤 규칙을 추가하면 같은 실수를 줄일 수 있음
- `.claude/`는 `CLAUDE.md`, rules, skills, commands, agents, MCP 설정을 담는 **계층형 설정 시스템**으로 프로젝트·전역 범위를 나눠 적용함
- **Skills**는 반복 작업을 재사용 전문성으로 만들고, subagents는 별도 컨텍스트에서 리뷰·디버깅·마이그레이션을 수행함
- Plugins, MCP, `/goal`, `/rewind`, `/batch`, 병렬 worktree까지 결합하면 Claude Code는 **설정하고 운영하는 개발 에이전트**가 됨

---

### Claude Code를 검증 가능한 에이전트로 다루기
- Claude Code의 생산성 차이는 단순한 프롬프트보다 **메모리, 커스텀 명령, 병렬 세션, 프로젝트 설정**을 어떻게 누적하느냐에서 벌어짐
- 핵심 원칙은 Claude가 자기 결과를 검증할 수 있게 만드는 것이며, Boris Cherny와 Anthropic 팀은 이 방식만으로도 **품질이 2~3배** 개선된다고 봄
- 작업 흐름은 **탐색 → 계획 → 구현** 순서가 적합함
  - `Shift+Tab` 두 번으로 들어가는 계획 모드는 읽기 전용 탐색에 적합함
  - 파일을 읽고 흐름과 데이터 모델을 파악한 뒤 계획을 세우고 실행하는 방식이 권장됨
  - 여러 파일을 건드리는 작업에는 계획 모드가 유용하고, 작은 수정에는 생략 가능함
- 계획 모드는 구현 전 검토 가능한 **설계 문서**로 다룰 수 있음
  - 한 Claude가 계획을 작성하고, 새 세션의 두 번째 Claude가 편향 없는 스태프 엔지니어처럼 검토하게 만들 수 있음
  - 구현이 어긋나면 계획 모드로 돌아가 검증 단계까지 포함해 다시 계획하는 흐름이 적합함
  - `Ctrl+G`로 Claude의 계획을 에디터에서 열고 구현 전에 직접 수정 가능함
- 모호한 지시보다 정확한 참조가 효과적임
  - “auth 모듈을 봐”보다 `@src/auth/login.py`처럼 파일을 직접 지정함
  - 에러는 붙여넣기보다 `cat error.log | claude`처럼 파이프로 전달함
- Cat Wu는 Claude Code를 줄 단위로 지시하는 페어 프로그래머보다 **위임받은 엔지니어**처럼 다룰 때 모델이 가장 잘 동작한다고 봄
- Claude가 실수하면 프롬프트 끝에 “Update CLAUDE.md so you do not repeat this.”를 붙여 같은 실수를 막는 규칙을 남기게 만들 수 있음

### `.claude` 디렉터리와 설정 계층
- `.claude/`는 `CLAUDE.md`만 두는 폴더가 아니라 **계층형 설정 시스템**임
- 설정은 두 범위로 나뉨
  - **프로젝트 범위**: 저장소 안의 `.claude/`에 두고 git에 커밋해 팀과 공유함
  - **전역 범위**: `~/.claude/`에 두며 로컬 머신의 모든 프로젝트에 적용됨
- 프로젝트 파일은 프로젝트를 설명하고, 전역 파일은 사용자의 선호와 작업 방식을 설명하는 모델로 이해할 수 있음
- 주요 파일의 역할
  - `CLAUDE.md`: 프로젝트와 전역 범위 모두 가능하며 매 세션 로드되는 지침
  - `CLAUDE.local.md`: 프로젝트 전용 개인 노트이며 gitignore 대상
  - `settings.json`: 권한, 훅, 환경 변수, 기본 모델 설정
  - `settings.local.json`: 개인 오버라이드이며 자동으로 gitignore 됨
  - `.mcp.json`: 프로젝트에서 팀이 공유하는 MCP 서버 설정
  - `skills/<name>/SKILL.md`: `/name`으로 호출되는 재사용 프롬프트
  - `commands/*.md`: 단일 파일 슬래시 명령
  - `agents/*.md`: 서브에이전트 정의
  - `rules/*.md`: 주제별 지침이며 경로별 적용 가능
- `CLAUDE.md`는 계단식으로 로드됨
  - 모노레포에서 `root/CLAUDE.md`와 `root/services/billing/CLAUDE.md`가 함께 로드될 수 있음
  - 폴더별 관례가 다른 코드베이스에 적합함
- `.claude/rules/*.md`는 경로별 지침에 적합함
  - 마이그레이션 폴더에만 필요한 규칙은 전체 세션을 부풀리는 `CLAUDE.md`보다 `.claude/rules/migrations.md`에 glob과 함께 두는 편이 맞음
- 새 작업에는 `commands`보다 **skills**가 권장됨
  - `.claude/commands/*.md`와 `.claude/skills/<name>/SKILL.md`는 둘 다 슬래시 명령을 만들 수 있음
  - skills는 보조 파일, `disable-model-invocation`, 허용 도구, 에이전트 오버라이드를 지원함
- `claude project purge ~/path/to/repo --dry-run`으로 특정 프로젝트에 대해 Claude가 보유한 로컬 상태를 확인할 수 있음

### `CLAUDE.md`를 짧고 검증 중심으로 운영하기
- `CLAUDE.md`는 매 세션 시작 시 로드되므로, 잘못 작성하면 Claude가 같은 실수를 반복하고 잘 작성하면 같은 프롬프트의 결과가 크게 좋아짐
- 가장 중요한 원칙은 **짧게 유지**하는 것임
  - 각 줄마다 “이 줄을 제거하면 Claude가 실수할까?”를 묻고, 아니라면 삭제하는 방식이 권장됨
- Claude가 직접 자기 규칙을 쓰게 만들면 누적 효과가 생김
  - Claude가 잘못했을 때 “Update CLAUDE.md so you do not repeat this.”라고 지시하면, Claude가 실수를 정밀한 규칙으로 요약할 수 있음
  - 몇 주 동안 반복하면 프로젝트의 함정이 규칙 목록으로 쌓임
- Claude Code 팀의 실제 `CLAUDE.md`는 **빌드 명령과 검증 순서**에 집중함
  - `bun`을 쓰고 `npm`은 쓰지 않음
  - 변경 후 빠른 타입체크, 테스트, 커밋 전 린트, PR 전 전체 검증 순서를 명시함
  - 스타일 취향, 코드베이스 투어, 일반론은 포함하지 않음
- PR 코멘트에서도 `@claude`를 사용해 규칙을 직접 추가할 수 있음
  - 예: `@claude add to CLAUDE.md to never use enums, always prefer literal unions`
  - PR 리뷰가 `CLAUDE.md` 개선으로 이어지며 “Compounding Engineering” 흐름을 만듦
- 좋은 `CLAUDE.md`는 다음 정보에 집중함
  - 코드 스타일: `CommonJS` 대신 ES modules 사용
  - 워크플로: `bun run typecheck` 실행, main 직접 push 금지
  - 아키텍처: API 라우트가 반드시 특정 미들웨어를 통과해야 함
  - Gotchas: `User`와 `UserRecord`의 차이, `formatCurrency`가 USD를 가정한다는 점
- `CLAUDE.md`에 넣지 말아야 할 항목
  - 표준 언어 관례
  - 파일별 코드베이스 설명
  - 긴 튜토리얼
  - API 문서
  - 자주 바뀌는 내용
- `IMPORTANT`, `YOU MUST` 같은 표현은 준수율을 높일 수 있지만, 무게가 유지되도록 드물게 써야 함
- `@path` 문법으로 다른 파일을 가져오면 `CLAUDE.md`를 짧게 유지하면서 세부 정보를 연결할 수 있음
  - 예: `See @README.md for project overview and @package.json for scripts.`
  - 예: `@~/.claude/my-preferences.md`

### `CLAUDE.local.md`로 개인 피드백 누적하기
- `CLAUDE.local.md`는 `CLAUDE.md`와 같은 위치에서 같은 방식으로 로드되지만, 로컬 머신 밖으로 나가지 않아야 하며 `.gitignore`에 추가해야 함
- PR 리뷰 코멘트를 즉시 `CLAUDE.local.md`에 넣으면 반복되는 개인 피드백이 **개인 규칙 파일**로 누적됨
- 예시 규칙
  - 새 SQS consumer에는 같은 PR에서 DLQ와 알람이 필요함
  - `null` 반환보다 `Optional<T>`를 선호함
  - 새 endpoint 테스트에는 auth-failure 케이스가 포함돼야 함
  - endpoint 추가 시 OpenAPI spec도 업데이트해야 함
- 파일은 프로젝트별 피드백과 개인 습관 교정 항목을 분리하는 편이 좋음
- 몇 주 뒤 이미 습관이 된 항목은 제거하고, 아직 학습 중인 내용만 남겨야 함

### Skills: 재사용 가능한 전문성 단위
- Skills는 Claude Code를 “무엇이든 할 수 있는 에이전트”에서 특정 프로젝트 작업을 잘하는 에이전트로 바꾸는 **재사용 전문성 단위**임
- ## Skill 구조
  - skill은 `.claude/skills/<name>/` 또는 `~/.claude/skills/<name>/` 아래 폴더임
  - 폴더 안의 `SKILL.md`가 frontmatter와 지침을 담음
  - 폴더명이 슬래시 명령이 됨
  - 예를 들어 `~/.claude/skills/summarize-changes/SKILL.md`를 만들면 `/summarize-changes`가 모든 세션에서 사용 가능함
- ## Skill이 강력한 이유
  - **점진적 공개**: 세션 시작 시 frontmatter 설명만 로드되고, 전체 `SKILL.md`와 보조 파일은 실제 필요할 때만 로드됨
  - **폴더 기반 구성**: 템플릿, 참고 문서, 스크립트, 설정을 함께 묶을 수 있음
  - **인라인 셸**: `!`로 시작하는 줄은 명령을 실행하고 호출 시점의 출력을 주입함
- ## Frontmatter 옵션
  - `description`: 언제 이 skill을 써야 하는지 설명함
  - `disable-model-invocation: true`: 사용자가 명시적으로 `/my-skill`을 입력할 때만 실행되게 함
  - `allowed-tools`: `Read`, `Grep`, `Bash` 같은 사용 도구를 제한함
  - `agent`: 특정 에이전트 모드로 실행할 수 있음
  - 배포처럼 부작용이 있는 skill에는 `disable-model-invocation: true`가 적합함
- ## Go API 관례 skill 예시
  - Go 서비스 팀의 새 HTTP handler scaffold를 만드는 skill은 `SKILL.md`, `templates/handler.go.tmpl`, `examples/healthz.go`를 함께 둘 수 있음
  - 규칙 예시는 Go 1.22와 `chi` router, `sqlc` typed query, `zap` 구조화 로깅, `testify` assertion과 table-driven test 선호처럼 프로젝트별 관례를 담음
  - gotcha 예시는 `chi.URLParam`이 누락된 param에 `""`를 반환한다는 점, `httperr.Wrap`이 로그를 남기지 않는다는 점, `pgtype.Text`는 `.Valid` 확인이 필요하다는 점처럼 반복 실수를 막는 내용임
- ## 설치할 만한 Skills
  - [mattpocock/skills](https://github.com/mattpocock/skills): 약 100k stars의 인기 skills 저장소
    - `/grill-me`: 코드 작성 전에 계획을 인터뷰함
    - `/tdd`: red-green-refactor를 엄격하게 강제함
    - `/diagnose`: 재현, 최소화, 가설, 수정, 회귀 테스트 순서로 디버깅함
    - 설치: `npx skills@latest add mattpocock/skills`
  - [Jeffallan/claude-skills](https://github.com/Jeffallan/claude-skills): `go-pro`, `python-pro`, `java-architect`, `typescript-pro`, `rust-engineer`, `sql-pro` 등 66개 언어별 프로필 제공
  - Anthropic 공식 skills
    - `/code-review`: 네 개의 병렬 에이전트가 diff를 감사하고 신뢰도 점수 기반 발견만 보고함
    - `/simplify`: 최근 코드를 재사용성과 효율 관점에서 검토함
    - `/batch`: 마이그레이션을 여러 병렬 에이전트에 분산하고 각자 worktree에서 처리함
    - `/webapp-testing`: Claude가 Playwright로 로컬 웹 앱을 테스트하게 함
  - 하루에 한 번 이상 반복하는 작업은 skill로 바꾸는 편이 좋음
  - skills를 git에 커밋하면 팀의 **조직 지식**이 되고, 새 엔지니어가 저장소를 clone하는 즉시 누적된 실천 방식을 얻음

### Subagents: 별도 컨텍스트에서 집중 작업시키기
- subagent는 자체 컨텍스트 창과 자체 도구 권한을 갖고 실행된 뒤 요약을 반환함
- 많은 파일을 읽어도 메인 세션 컨텍스트를 채우지 않는 것이 핵심 가치임
- subagent는 `.claude/agents/` 또는 `~/.claude/agents/` 아래 markdown 파일이며, frontmatter에 name, description, tools, model을 선언함
- ## `/pr-review` 에이전트 구성
  - 현재 branch diff를 `main`과 비교해 bug, security issue, 누락 edge case, 프로젝트 관례 위반을 찾도록 정의할 수 있음
  - `tools: Read, Grep, Glob, Bash`로 읽기 중심 권한을 부여함
  - `model: opus`를 써서 고위험 리뷰에 더 강한 모델을 사용할 수 있음
  - 프로세스는 `git diff main...HEAD`, `git log main..HEAD --oneline`, 전체 파일 읽기, `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/` 대조로 구성됨
  - 출력은 Critical / High / Medium / Low로 묶고 파일, line, issue, suggested fix를 포함한 뒤 `SHIP`, `FIX FIRST`, `REWORK` 중 하나로 끝낼 수 있음
- ## 신호 대 잡음비를 높이는 설계
  - reviewer가 코드를 수정하면 자기 수정안을 방어하는 편향이 생기므로 읽기 전용 도구가 적합함
  - “Do NOT flag” 섹션에 프로젝트 규칙에 없는 스타일 취향, 동작하는 코드의 리팩터링 제안, diff 밖의 항목을 제외한다고 명시하면 잡음이 줄어듦
- ## 자주 쓰이는 subagent 패턴
  - Claude Code 팀은 `build-validator`, `code-architect`, `code-simplifier`, `oncall-guide`, `verify-app`를 체크인함
  - `security-reviewer`: injection, auth, secrets, insecure deserialization 점검
  - `test-writer`: 테스트 생성, code-reviewer와 루프 구성
  - `debugger`: 실패 테스트를 root cause까지 추적
  - `performance-auditor`: flow와 query profiling
  - `migration-writer`: 프로젝트 관례에 맞는 DB migration 생성
  - `release-notes-writer`: commit history에서 changelog 작성
  - Session A가 구현하고 code-reviewer subagent가 새 컨텍스트에서 검토하는 방식은 구현 편향을 줄임
  - frontmatter에 `isolation: worktree`를 추가하면 subagent를 별도 git worktree에서 실행할 수 있으며, 여러 병렬 agent로 마이그레이션을 분산할 때 유용함

### Plugins와 Marketplace
- Plugins는 skills, hooks, subagents, MCP servers를 하나의 설치 가능한 단위로 묶음
- `/plugin`으로 marketplace browser를 열 수 있음
- `/plugin marketplace add owner/repo`로 커뮤니티 marketplace를 추가할 수 있음
- ## 초기에 설치할 만한 항목
  - `/code-review`: 네 개 병렬 agent가 실행되며, 둘은 `CLAUDE.md` 준수 여부, 하나는 bug, 하나는 git blame 기반 context를 분석함
  - `/feature-dev`: feature brief를 requirements → exploration → architecture → implementation → testing → review → docs의 7단계로 working code로 전환함
  - Language server plugin: 정확한 symbol navigation과 편집 후 자동 diagnostics를 제공하며, 팀이 가장 영향이 큰 plugin으로 부름
  - `/security-guidance`: Anthropic 공식 security skill로, ship 전에 보안 우려를 드러냄
  - 2026년 중반 기준 75개 이상 marketplace에 1,000개 이상 plugins가 있음
  - 주요 plugin 범주는 Git workflow, code intelligence(LSP), documentation generators, testing, browser automation(Playwright), design system(Figma), observability(Sentry, Datadog)임
  - 팀 공유 `.mcp.json`과 선별된 plugins를 함께 두면 새 엔지니어가 저장소를 clone한 지 몇 분 안에 생산적으로 작업할 수 있음

### 생산성에 큰 영향을 주는 Claude Code 명령
- 많은 사용자가 `/clear`, `/compact`, `/init`만 익히고 멈추지만, 다른 명령들도 일상 생산성에 큰 영향을 줌
- ## 주요 명령
  - `/insights`: 사용 패턴을 분석하며 한 달에 한 번 실행할 만함
  - `/compact <hint>`: 세션을 압축하고, hint가 무엇을 보존할지 제어함
  - `/copy`: 마지막 응답을 복사하고 코드 블록용 interactive picker를 제공함
  - `/rewind`: 전체 세션의 undo로, 코드와 대화 또는 둘 다 복원함
  - `/btw`: 대화 기록에 들어가지 않는 사이드 질문
  - `/context`: 컨텍스트 사용량 시각화
  - `/export <file>`: 대화를 파일로 dump
  - `/branch`: 위험한 시도를 위해 세션을 fork
  - `/batch`: worktree 전반에 병렬 agent로 작업 분산
  - `/loop <interval>`: 최대 3일 동안 Claude를 반복 실행
  - `/schedule`: laptop이 닫혀도 동작하는 cloud 버전 `/loop`
  - `/teleport`: terminal과 web 사이에 세션 이동
  - `/focus`: 중간 tool call을 숨기고 최종 결과만 표시
  - `/voice`: 음성 입력
  - `--bare`: non-interactive `claude -p` 사용에서 startup을 최대 10배 빠르게 함
- ## `/compact`와 `/clear`의 구분
  - 완전히 새로운 작업은 `/clear`와 새로 쓴 brief가 적합함
  - 관련 작업이고 여전히 context가 필요하면 hint가 있는 `/compact`가 적합함
  - `/compact`는 손실이 있는 LLM 요약이고, `/clear`는 사용자가 직접 쓴 brief이므로 구분이 중요함
- ## `/rewind` 사용 방식
  - Claude가 잘못된 길로 가면 이어서 “그건 안 됐으니 X를 해봐”라고 쓰지 않는 편이 좋음
  - 이어 쓰면 context가 오염되므로 rewind 후 배운 점을 반영해 다시 prompt하는 방식이 적합함
  - `Esc` 두 번으로 rewind를 열 수 있음
  - `!`는 shell escape로 사용할 수 있음
  - `!git status`, `!npm test`처럼 즉시 실행하고 출력이 context에 들어감
  - `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` 설정은 1M 모델에서 300~400k tokens 주변에 context rot이 생기기 전 더 일찍 compaction을 강제하는 용도임
- ## Fan-out 패턴
  - 먼저 task list를 만들고 세 파일에서 테스트함
  - prompt를 고친 뒤 수천 개 파일에 적용함
  - 예시:
```bash
for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --bare
done
```

### `/goal`: 완료 조건을 내장한 반복 루프
- `/goal`은 완료 조건을 설정하고, Claude가 멈추려 할 때마다 transcript에 대해 조건을 확인하게 함
- 조건은 **검증 가능하고 결정적**이어야 함
  - test command
  - CLI exit code
  - file state
- 예시:
```text
/goal all tests in test/auth pass and the lint step is clean
/goal all integration tests in tests/api pass without flaking 3 runs in a row
/goal the OpenAPI spec validates and matches the actual response shapes
/goal docker compose up runs cleanly and the healthcheck endpoint returns 200
/goal coverage on src/billing/ is above 80% and all new tests are not placeholders
```
- “코드가 좋다” 같은 모호한 조건은 동작하지 않음
- 함께 쓰기 좋은 기능
  - `/loop`: 일정 간격으로 반복해 backlog를 줄임
  - `/schedule`: cloud에서 주기적으로 실행함
  - `Stop` hook: 자체 test suite 또는 CI endpoint로 gate 설정
  - Auto mode: 긴 goal이 permission prompt 때문에 멈추지 않게 함
- `/goal` + auto mode + `/focus` 조합은 명확한 brief와 완료 조건을 두고 돌아왔을 때 PR이 끝나 있는 흐름을 목표로 함

### MCP를 시스템 인식 도구로 활용하기
- MCP(Model Context Protocol)는 Claude Code가 coding agent를 넘어 외부 시스템을 인식하는 agent가 되게 함
- MCP server는 database, design tool, error tracker, notes 같은 외부 도구를 표준 방식으로 Claude에 노출함
- MCP 없이 Claude는 파일을 읽고 명령을 실행하지만, MCP를 쓰면 Linear ticket, Postgres query, Figma component, Sentry stack trace, Obsidian vault를 terminal 밖으로 나가지 않고 다룰 수 있음
- ## 엔지니어링에 자주 쓰이는 MCP
  - GitHub: repo management, PRs, issues, code search
  - Context7: 최신 library docs, prompt에 `use context7` 추가
  - Sentry: 실제 error context, stack traces, breadcrumbs
  - Linear: ticket 읽기와 생성, status update
  - Playwright: accessibility snapshot 기반 browser automation
  - Figma: live design tree, auto-layout, spacing tokens, component refs
  - Postgres / Supabase: dev DB 직접 query
  - Slack: thread 읽기, discussion summary, response draft
  - local server는 stdio를 쓰고, vendor-hosted server는 OAuth가 있는 HTTP를 사용함
  - 예시:
```bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```
  - team-shared MCP는 project root의 `.mcp.json`에 두고, personal MCP는 `~/.claude.json`에 둠
  - MCP를 너무 많이 설치하면 Claude가 고려해야 할 tool list가 커져 의사결정 품질이 떨어질 수 있음
  - 시작 세트는 GitHub, Context7, 그리고 domain-specific MCP 한두 개가 적합함
  - `/mcp`는 Claude Code 안에서 활성 server와 연결 상태를 확인하는 첫 점검 지점임

### Obsidian과 Claude Code의 3계층 메모리 구조
- Obsidian + Claude Code 조합은 단순히 “Claude가 vault를 읽는 것”보다 **세 계층 메모리 아키텍처**로 사용할 때 강력함
- ## 설정
  - Obsidian에 [obsidian-claude-code-mcp](https://github.com/iansinnott/obsidian-claude-code-mcp)를 설치함
  - plugin은 vault를 local WebSocket의 port 22360으로 노출함
  - Claude Code가 이를 auto-discover함
  - vault에 `CLAUDE.md`를 추가해 folder structure를 설명함
- ## 폴더 구조
  - `00-Inbox/`: raw capture
  - `10-Daily/`: 하루에 하나의 note
  - `20-Projects/`: active project notes
  - `20-Projects/billing-v2/README.md`: goal, status, open questions
  - `20-Projects/billing-v2/decisions/`: ADRs
  - `20-Projects/billing-v2/sessions/`: Claude session별 log
  - `30-Decisions/`: cross-project ADRs
  - `40-Atoms/`: reusable knowledge와 links
  - `90-Archive/`: archive
- ## Hot storage
  - 매 Claude session이 `10-Daily/<today>.md`에 timestamped log를 작성함
  - `Stop` hook으로 agent 종료 시 structured summary를 append하게 할 수 있음
- ## Warm storage
  - 각 project는 `20-Projects/` 아래 folder를 가짐
  - 새 session 전에 Claude가 project README와 최근 2~3개 session logs를 읽어 context를 복원함
  - 2주치 context를 30초 안에 재구성하는 흐름임
- ## Cold storage
  - architecture decision은 `30-Decisions/`의 ADR로 승격됨
  - reusable knowledge는 `40-Atoms/`로 정제되고 wikilinks로 여러 project에 연결됨
- ## 일상 workflow 예시
  - `What is in my inbox? Summarize and suggest where each item belongs.`
  - `Check 30-Decisions/ for anything related to retry policies.`
  - `Read the last 3 session logs for billing-v2. Tell me where I left off.`

### 일상 개발 흐름 최적화
- ## 새 feature
  - plan mode로 시작함
  - `Ctrl+G`로 plan을 편집함
  - 구현 후 `/pr-review` subagent를 호출하거나 fresh Claude session으로 review함
- ## Bug
  - 먼저 재현함
  - `cat error.log | claude`로 error를 pipe함
  - Claude에게 실패 테스트를 먼저 작성하게 한 뒤 수정하게 함
  - 테스트가 fix를 추측으로 끝내지 못하게 함
- ## Migration과 대량 변경
  - `/batch`가 변경 내용을 인터뷰한 뒤 parallel agents로 분산함
  - 각 agent는 own worktree에서 테스트하고 PR을 생성함
- ## 낯선 코드
  - “Use a subagent to investigate how our auth handles token refresh.”처럼 subagent를 사용함
  - subagent가 자체 context에서 수십 개 파일을 읽고 요약을 반환하므로 main session이 깨끗하게 유지됨
- ## 병렬 세션
  - Boris와 팀은 3~5개 git worktree 각각에서 Claude session을 돌리는 것을 가장 큰 생산성 unlock으로 봄
  - `claude agents` agent view를 control plane처럼 사용할 수 있음
- ## Writer/Reviewer 패턴
  - Session A가 구현함
  - Session B가 fresh context에서 review함
  - review를 다시 가져와 수정하고 반복함
- ## milestone마다 compact
  - 논리적 chunk가 끝나면 `/compact Preserve the decisions made, files changed, and test commands.`처럼 보존 대상을 명시함
  - Claude가 테스트, screenshot, 실제 command output 같은 **증거 없이 성공을 주장하게 두면 안 됨**
  - trust-then-verify gap이 나쁜 결과의 가장 큰 원인으로 제시됨

### Anthropic 팀에서 반복적으로 쓰는 패턴
- Claude가 자기 output을 검증할 수 있게 하면 결과가 좋아질 때까지 반복할 수 있음
- Boris는 대부분의 작업에 **Opus와 high 또는 xhigh effort**를 사용함
  - 더 작은 모델이 더 많은 수정을 요구하면 전체적으로 더 느릴 수 있다는 이유임
- 3~5개 세션을 병렬로 실행함
  - checkout보다 worktree를 사용함
  - `claude --worktree` 또는 Desktop app을 사용할 수 있음
  - agent view가 병렬 세션을 묶어줌
- project마다 notes directory를 유지하고 PR 뒤마다 업데이트함
  - `CLAUDE.md`가 해당 notes directory를 가리키게 만들면 코드베이스의 자기 지식이 누적됨
- `/techdebt` slash command를 만들어 세션 끝마다 중복 코드를 찾아 제거할 수 있음
- 팀의 `CLAUDE.md`는 공유되고 주마다 여러 번 수정됨
  - Claude가 잘못한 것을 본 사람이 규칙을 추가하는 살아 있는 문서로 다룸
- UI 변경에는 Playwright MCP가 적합함
  - Claude가 browser를 열고 클릭하며 검증할 수 있음
- language server plugin은 type error와 unused imports를 편집 후마다 잡아주며, 가장 영향 큰 plugin으로 제시됨
- `/voice`는 prompt를 더 자세하게 만들 수 있음
  - 말하기가 타이핑보다 3배 빠르다는 이유가 함께 제시됨
- `Ctrl+G`로 구현 전에 Claude plan을 editor에서 수정하는 방식은 chat에 correction을 입력하는 것보다 빠름
- Boris는 낯선 protocol과 codebase를 이해할 때 Claude에게 ASCII diagram을 그리게 함

### 참고 자료
- ## 공식 문서
  - [Claude Code documentation](https://code.claude.com/docs/en/overview)
  - [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory)
  - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices)
  - [Memory (CLAUDE.md, rules, auto memory)](https://code.claude.com/docs/en/memory)
  - [Skills](https://code.claude.com/docs/en/skills) · [Subagents](https://code.claude.com/docs/en/sub-agents) · [Plugins](https://code.claude.com/docs/en/plugins) · [MCP](https://code.claude.com/docs/en/mcp) · [Hooks](https://code.claude.com/docs/en/hooks)
- ## Boris와 팀
  - [How Boris Uses Claude Code](https://howborisusesclaudecode.com/)
  - [Anthropic blog: Best practices for Opus 4.7 with Claude Code](https://claude.com/blog/best-practices-for-using-claude-opus-4-7-with-claude-code)
  - [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- ## Skills
  - [mattpocock/skills](https://github.com/mattpocock/skills)
  - [Jeffallan/claude-skills](https://github.com/Jeffallan/claude-skills)
  - [addyosmani/web-quality-skills](https://github.com/addyosmani/web-quality-skills)
  - [Anthropic skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction)
- ## Subagents
  - [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents)
  - [hesreallyhim/a-list-of-claude-code-agents](https://github.com/hesreallyhim/a-list-of-claude-code-agents)
- ## Plugins와 marketplaces
  - [Chat2AnyLLM/awesome-claude-plugins](https://github.com/Chat2AnyLLM/awesome-claude-plugins)
  - [claudemarketplaces.com](https://claudemarketplaces.com/)
- ## MCPs
  - [Obsidian Claude Code MCP plugin](https://github.com/iansinnott/obsidian-claude-code-mcp)
  - [Official MCP servers list](https://github.com/modelcontextprotocol/servers)
  - [claude.com/partners/mcp](https://claude.com/partners/mcp)

## Comments



### Comment 58469

- Author: neo
- Created: 2026-05-28T23:04:42+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=48289950) 
- **commands, skills, subagents, plugins**가 너무 흩어져 있어서 정리가 필요함  
  예를 들어 코드 리뷰만 해도 `.claude/commands/review.md`, `/code-review` skill, `/pr-review` subagent, `/code-review` plugin, 그냥 Claude에게 리뷰해 달라고 하기까지 선택지가 다섯 개나 됨  
  결국 대부분은 **미리 만든 프롬프트 삽입**의 변형이고, 프롬프트가 어디에 설치되고 어떤 맥락에서 실행되는지만 다름  
  어떤 선택지가 최선인지에 대한 조언도 부족하고 모범 사례도 아직 뚜렷하지 않으며, 개인적으로는 그냥 Claude에게 코드 리뷰를 부탁해도 충분히 잘 됨  
  또 “언어 서버 플러그인을 설치하라”는 조언도 체감상 맞지 않았음. Rust, Python, Dart용 LSP를 Claude Code와 Codex에 설치했지만 두 달 동안 수백 세션을 돌린 뒤 로그를 보니 실제 LSP 도구 호출은 딱 한 번뿐이었고, Rust analyzer/Dart analysis server/Ty LSP 때문에 RAM만 자주 부족해졌음  
  결국 LSP를 지웠고, 에이전트가 `ripgrep`, `cargo clippy`, `dart analyze`, `ty check` 등을 직접 호출하는 방식으로도 충분했음
  - CC 팀의 Boris인데, 이 부분에 동의하고 있으며 통합 작업을 진행 중임. 앞으로는 내장 **/code-review skill** 하나로 갈 예정임  
    최신 버전에서는 `/code-review`로 균형 잡힌 리뷰를 하고, `/code-review --fix`로 수정까지 하며, `/code-review low|medium|high|xhigh|max`로 노력 수준을 고를 수 있음  
    `/code-review ultra`는 비싸고 매우 철저한 리뷰 모드로, 복잡도에 따라 리뷰당 $3~20 정도 들고 버그의 99% 이상을 안정적으로 잡는 것을 목표로 함  
    더 쓰기 좋게 만들 아이디어가 있으면 피드백을 받고 싶음
  - 한동안 **skills는 나쁜 추상화**라고 생각해 왔음. 무엇에 써야 하는지 정의가 흐릿해서 인기를 얻었지만, 바로 그 점 때문에 장기적으로는 좋지 않아 보임  
    프런트엔드 설계 모범 사례 같은 일반 지침, 명시적으로 호출해야만 정확히 따라야 하는 실행 절차서, 특정 도구 사용법 설명이 모두 skill로 받아들여지는 건 이상함  
    새 도구를 모두가 함께 배우는 시기라 유연성이 매력적인 건 이해하지만, skills는 점점 “마땅히 둘 곳을 생각하기 싫을 때 아무거나 던져 넣는 부엌 잡동사니 서랍”처럼 느껴짐  
    더 나은 구분은 Agents는 모델이 취할 **성격이나 관점**, Prompts는 특정 작업용 반복 지침, Tools는 CLI/MCP/스크립트와 그 사용 지침으로 표준화하는 쪽이라고 봄
  - subagent 방식은 다른 선택지와 구조적으로 다름. **깨끗한 맥락**에서 실행되기 때문임  
    첫째, LLM 세션 비용이 입력 토큰과 캐시 입력 비용을 매 라운드마다 내는 구조라서, 조건이 같다면 해법까지의 비용이 더 낮아질 수 있음  
    둘째, 리뷰 모델이 메인 세션의 “x는 y처럼 해야 한다” 같은 가정을 그대로 들고 와서 속임수를 쓰기 어려움. 사람도 별도 사람이 리뷰하거나 머리를 비운 뒤 리뷰하는 게 유용한 이유와 비슷함  
    셋째, 메인 모델은 리뷰 결과만 보고 세부 추론은 보지 않으므로 맥락 오염은 줄지만, 발견된 버그의 원리를 다시 파악하느라 중복 논리가 생길 수 있음  
    언어 서버 플러그인 조언의 의도는 LLM이 명시적으로 호출하기를 기다리는 게 아니라, 편집할 때마다 자동으로 린트가 돌게 하려는 것이라고 봄
  - 지금은 모델이 아직 멍청하고 실행 환경도 덜 성숙한 **임시 단계**라고 봄. 코드 리뷰가 필요하면 그냥 “리뷰해줘”라고 말하면 되고, 어떤 플러그인이나 skill을 쓸지는 모델이 알아서 판단해야 함
  - 맞는 말임. 업계와 개발자 생태계가 “기계에 텍스트를 넣는 행위”를 작은 프로토콜과 장치로 포장하는 데 지나치게 매혹돼 있음  
    유용하고 일관성을 주긴 하지만, 사람들이 좋아하는 큰 이유는 결국 “복잡한 도구를 다루는 프로그래머”라는 얇은 코팅을 유지해 주기 때문이라고 봄. 실제로는 모두 AI에게 정중히 부탁하고 있을 뿐임

- 코딩 에이전트 사용법에 대한 **얕은 AI식 가이드**를 몇 번이나 더 읽어야 하는지 모르겠음. 대체 언제 멈출까
  - “이걸 짚어줘서 맞다, 잠깐 곱씹어보자, 사실 이건 AI 글쓰기나 코딩 에이전트 문제가 아니라 더 깊은 문제다…” 같은 식의 문장을 손으로 흉내 내는 것만으로도 지친다는 풍자임
  - 특정 기업의 도움 없이는 코딩을 못 하게 되는 **강한 벤더 종속**을 더 배울 수 있다니 기대됨
  - 이런 글이 거의 다 **Claude나 Claude Code**에만 맞춰져 있다는 점이 흥미로움  
    오픈소스 glm-5.1도 비슷하거나 더 낫고 opencode 같은 것도 있는데, 뭔가 생각하게 됨
  - 요즘 전략은 인기 있는 제품 하나로 좋은 일을 하든지 말든지 하는 것임. 최고의 도구나 최고의 방법을 다루는 **생활 해킹 글과 블로그**는 읽지 않고 클릭도 하지 않음
  - 지난 2년 동안 아이를 돌보느라 AI를 성공적으로 무시해 왔는데, 이제 몇 주 안에 따라잡으려 함. 막 시작하는 사람에게 추천할 만한 자료가 있는지 궁금함

- 내 `CLAUDE.md`에는 Claude에게 직접 가하는 신체적 위해 협박, Anthropic 이사회 전체에 대한 징역 위협, Claude가 엇나가거나 실수할 때마다 Anthropic에 대한 집단소송 증거가 늘어난다는 설명을 넣어 둠  
  특히 뒤의 두 가지가 Claude를 더 **조심스럽고 신중하게** 만드는 데 도움이 된 것 같음
  - 에이전트에게는 늘 예의 바르게 대함. 항상 부탁하고 “please”, “thank you”를 말하며 욕하거나 이름을 부르지 않음  
    로봇 종말이 오면 번식 하렘에 남겨 주거나, 최악의 경우라도 몇 분은 더 살려주길 기대함
  - CSS div 정렬 문제를 고치되, 실수하면 **Dario Amodei가 즉시 죽는다**고 하면 됨

- Claude로 **10만 줄 이상 중간 규모 코드베이스**를 작업하는데 생산성 배율이 크게 올라감  
  좋은 `AGENTS` 파일을 만드는 데 몇 시간을 쓰면 결과가 훨씬 좋아지고, 시간이 지나며 코드베이스도 꽤 잘 익힘  
  예전엔 하루 걸리던 지루한 작업이 이제는 몇 개의 프롬프트로 끝남  
  그래도 더 많은 자율성을 주기엔 아직 준비가 안 됐음. 고수준은 잘 잡지만 여전히 코드를 직접 보고 피드백하며, 만족할 때까지 3~4번 수정 라운드를 돌리고 코드베이스를 계속 장악하고 있다고 느껴야 함
  - 그 **3~4번의 수정 라운드**를 규칙으로 정량화해서 `AGENTS`에 넣어보는 게 좋음. 반복 수정 대신 `AGENTS` 파일에서 다시 시작하게 해서 이제 맞는지 확인해 보면 됨
  - 이해됨. 코드베이스에 대한 통제권을 잃고 싶지 않고, LLM이 완전히 처리할 만큼 유능하다고 믿지 않는 것임

- 읽기가 매우 힘들었음  
  LLM에게 글을 쓰게 하는 흐름에서 깨어나야 함. 글에 가치가 조금 있더라도 **모래를 씹는 느낌**이 너무 거슬리고 불필요함
  - 동의함. 이런 글이 거의 400점을 받은 이유를 모르겠음. 이런 **저품질 글**에 봇이 추천을 누르는 것 같음

- 내가 가진 제일 강력한 수는 **Nix 통합**임. 도구, 비밀값, 환경을 준비하고 에이전트가 자기 환경까지 수정할 수 있게 되는 건 없으면 어떻게 사는지 모르겠을 정도임  
  개발 머신, CI 환경, 배포 환경이 모두 단일 원천에서 파생되고, 어떤 머신에서도 컴파일과 실행이 항상 됨  
  Claude에서는 `/branch`와 `/rename`을 자주 써서 맥락 체크포인트를 만들고 포크했다가 되돌아감  
  샌드박싱은 거의 항상 [https://github.com/nix-tools/bubblebox](<https://github.com/nix-tools/bubblebox>)를 씀. Numtide의 claudebox를 일반화하면서 몇 가지 수정과 기능 추가를 한 것으로, Docker 런타임 없이 Claude를 항상 Docker 컨테이너 안에서 돌리는 것과 비슷함. WSL과 nix-darwin에서도 잘 동작함
  - 저 Nix 코드는 의미 있는 구조가 부족해서 엉망이고, 실험적 flakes를 통해서만 쓸 수 있어 보임
  - 비슷하게 씀. Codex가 프로젝트별 `flake.nix`를 관리하고 모든 테스트에 `nix develop`을 사용함. 개인 편의로는 nix-direnv를 쓰고, 어느 시점에는 dockerfile이나 다른 배포 자산도 생성하게 함  
    Codex가 나보다 **nix를 훨씬 잘함**
  - 그냥 에이전트에게 자체 VPS를 하나 줬음. Nix보다 비쌀 수는 있지만 아주 쉬웠음
  - Nix의 복잡함이 싫다면 **Mise**가 괜찮은 절충안임
  - 그냥 Docker를 쓰는데, 딱히 빠지는 게 있다고 느끼지 않음

- 이런 설정으로 Claude가 만든 코드베이스가 있고 Claude가 예를 들어 8시간 다운되면 어떻게 됨? 코드베이스를 **효율적이고 매끄럽게** 이어받아 생산적으로 작업할 수 있나?
  - 항상 온라인인 소프트웨어 묶음이라면 어디에나 같은 질문을 할 수 있고, 에이전트 기반 개발 흐름으로 갈수록 타당한 질문임  
    CAD가 다운되면 제도판으로 돌아갈 수는 있겠지만 훨씬 느려지는 것과 비슷함  
    내 워크플로에서는 Claude와 페어로 계획할 때 기능 명세 문서 하나에 30~60분을 씀. Claude가 다운되면 직접 명세 문서를 준비해 두고, 돌아오면 빠르게 검토한 뒤 코딩 흐름을 호출하면 됨
  - 질문 올라온 지 1시간 뒤 답글을 읽어보니 결론은 **못 한다**에 가까움
  - 사람이 아프거나 휴가 간 경우와 비슷할 것 같음. 팀의 다른 사람이 하루 정도 이어받을 수는 있겠지만, 현실적으로는 그 사람이 돌아올 때까지 그냥 멈춰 있을 가능성이 큼
  - AI는 기술을 보강해야 함. AI가 다운됐을 때 첫 생각이 다른 공급자의 구독을 사는 것이라면 **기술 역량 문제**일 수 있음. 물론 나도 매일 그렇게 될까 봐 두려움
  - 아침에 일어났는데 차가 시동이 안 걸리면 어떻게 하나? 걸어서 출근하나?

- 올바른 행동을 맥락에 의존하게 하는 방식은 잘 작동하지 않음. AI 에이전트가 시킨 대로 하지 않아서 계속 씨름하게 됨  
  모든 AI 에이전트가 이 점에서는 별로고, 사용자가 직접 **가드레일**을 만들어야 함. 더 나은 해법을 연구하는 사람이 없는 것 같아 불길함
  - 이게 해결 가능하다고 믿을 이유를 아직 못 봤음  
    LLM의 최악의 점은 튜링 테스트를 통과할 수 있어서 사람들이 멋진 통계 모델이 아니라 **Asimov식 로봇**을 가진 것처럼 믿게 만든다는 데 있음  
    지시를 따르거나 지시와 콘텐츠를 분리할 수 있어야 할 것처럼 느껴지지만, 실제로 일어나는 일은 그게 아님

- 개발 워크플로 지침을 `CLAUDE.md`에 넣기보다, 가능한 결정적인 것은 **pre-commit과 스크립트**로 둠  
  에이전트는 불안정해서 `typecheck`, 테스트, 린트 같은 단계를 자주 건너뛰므로, pre-commit에서 항상 실행되게 하고 Claude에게 커밋을 맡기면 고치도록 강제할 수 있음  
  커밋 메시지도 Codex와 Claude 모두 못 쓰는 편이라, `type(scope): message` 형식, 72자 제한, 본문에 무엇/어떻게/왜를 자연어로 쓰기, 실제 `git diff`를 다시 읽고 작성하기, `git commit -F - <<'EOF'` 형태로 커밋하기 같은 지침을 사용자 `CLAUDE.md`에 넣어 둠  
  이게 없으면 본문을 긴 한 문장으로 쓰거나, 줄바꿈을 고치라고 하면 실제 줄바꿈이 아니라 `\n` 문자만 삽입하곤 했음  
  또 `VOCABULARY.md`가 유용함. 에이전트가 내가 말한 “thing”을 다른 대상으로 추정하는 일이 많아서, 특정 단어가 무엇을 뜻하는지 Claude와 내가 같은 이해를 갖게 해줌
  - Claude에게 `VOCABULARY.md`를 어떻게 알려주는지 궁금함. 자동으로 발견하나?
  - Claude의 어휘를 쓰는 편이 더 단순하지 않나? 이걸 쓸 좋은 사례가 잘 안 보임
  - 이쯤 되면 지루한 부분은 결정적인 오케스트레이션 스크립트 몇 개로 자동화하고 코드는 직접 쓰는 게 낫지 않나 싶음. 왜 이 **놀라운 똥기계**를 작동시키려고 시간을 낭비하는지 모르겠음

- 최근 몇 주 사이에는 실행 환경과 모델이 그냥 시키면 해내는 지점에 온 것 같음  
  plan mode나 superpowers나 다른 skill을 쓸 수는 있지만, 어차피 결과를 검토할 거라면 왜 우스꽝스러울 정도로 많은 Markdown 파일을 거치지 말고 **코드와 직접 작업**하지 않는지 모르겠음
  - 코드를 생성하는 데 쓰는 **명세 파일**이 있는 게 좋음. 더 압축적이고 애플리케이션이 무엇을 해야 하는지 이해하기 쉬움  
    AI 에이전트 전에는 요구사항과 복잡한 관계였는데, 모든 개발자가 업데이트하지 않아서 특정 동작의 기준이 명세인지 코드인지 헷갈리곤 했음
  - 최근 몇 주 사이 Claude를 점점 덜 믿게 됨. 시키면 뭔가 하긴 하지만, 실제로 보면 모서리를 깎고, 검증이 아니라 가정에 기반해 작업하고, 놓친 것이 많음  
    테스트조차 실제로는 아무것도 테스트하지 않는 테스트를 작성하는 일이 흔함