▲

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

 (arps18.github.io)
1P by GN⁺ | ★ favorite | 댓글 1개
  • 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: 약 100k stars의 인기 skills 저장소
      • /grill-me: 코드 작성 전에 계획을 인터뷰함
      • /tdd: red-green-refactor를 엄격하게 강제함
      • /diagnose: 재현, 최소화, 가설, 수정, 회귀 테스트 순서로 디버깅함
      • 설치: npx skills@latest add mattpocock/skills
    • 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를 고친 뒤 수천 개 파일에 적용함
    • 예시:
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
  • 예시:
/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를 사용함
    • 예시:
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를 설치함
    • 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을 그리게 함

참고 자료

함께 보면 좋은 글 β

▲
GN⁺   [-]
Hacker News 의견들

  • 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를 씀. 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를 점점 덜 믿게 됨. 시키면 뭔가 하긴 하지만, 실제로 보면 모서리를 깎고, 검증이 아니라 가정에 기반해 작업하고, 놓친 것이 많음
      테스트조차 실제로는 아무것도 테스트하지 않는 테스트를 작성하는 일이 흔함
답변달기