주맨의 개발노트

Claude Code를 프로젝트에 적극적으로 활용하면서 개발 속도는 확실히 빨라졌습니다. 새 화면의 기본 구조를 만들고, 반복적인 보일러플레이트를 작성하고, 유사한 패턴을 이어가는 작업에서 특히 효과가 컸습니다.그런데 속도가 빨라진 만큼 새로운 문제가 생겼습니다. 코드 리뷰에서 MVI 패턴 위반이 발견되기 시작했습니다. CLAUDE.md에 MVI 규칙을 상세히 적어뒀는데도, Agent가 생성한 코드가 실제로 그것을 따랐는지 보장할 수 없었습니다.이 글은 그 문제를 해결하기 위해 마틴 파울러의 Harness Engineering 개념을 참고하고, Detekt 커스텀 룰을 Sensor로 도입한 경험을 정리한 기록입니다.Agent가 MVI 규칙을 어겼다제 프로젝트의 feature 모듈은 MVI 패턴을 표준으로..

들어가며Claude Code를 프로젝트에 적극적으로 활용하다 보면, 빠르게 코드를 만들어주는 만큼 팀 컨벤션을 놓치는 장면도 자주 보게 됩니다. 저희 팀에서는 특히 디자인 시스템 컴포넌트를 사용해야 하는 화면에서 Claude가 Material3 기본 컴포넌트를 선택하는 문제가 반복됐습니다.이 글은 CLAUDE.md로 규칙을 알려주는 것에서 한 단계 더 나아가, PostToolUse 훅으로 디자인 시스템 위반을 자동 감지한 경험을 정리한 기록입니다. 핵심은 Claude에게 더 길게 설명하는 것이 아니라, 반드시 지켜야 하는 규칙을 코드로 검사하는 구조를 함께 두는 것입니다.Claude가 Material3 AppBar를 사용했다새 화면을 만들 때 Claude에게 맡기면 Screen, Scaffold, Vie..

들어가며Claude Code로 작업을 맡겨두고 다른 일을 하다 보면 "언제 끝났지?" 하고 화면을 계속 확인하게 됩니다. 특히 여러 프로젝트를 동시에 돌릴 때는 어느 인스턴스가 완료됐는지도 알기 어렵습니다. Android Studio 플러그인, VS Code 터미널, 일반 터미널까지 열어두면 상황은 더 복잡해집니다.저도 처음에는 그냥 터미널 탭을 왔다 갔다 하면서 확인했습니다. 그런데 이게 생각보다 흐름을 많이 끊었습니다. 아직 안 끝난 작업을 확인하러 들어갔다가 다시 원래 하던 일로 돌아오는 일이 반복됐고, 어떤 때는 Claude Code가 이미 제 응답을 기다리고 있는데도 한참 뒤에 알아차리기도 했습니다.그래서 Claude Code의 Hook 시스템으로 macOS 네이티브 알림을 붙였습니다. 제가 실..

들어가며Claude Skill을 처음 만들 때는 보통 "이걸 어떻게 호출하지?"부터 생각하게 됩니다. 저도 처음에는 비슷했습니다. 그런데 디자인 시스템 관련 Skill을 정리하면서 방향이 조금 달라졌습니다. 제가 원한 것은 호출 가능한 기능 세트가 아니라, Claude가 언제 물어봐도 같은 기준으로 답하게 만드는 내부 판단 레이어였습니다.그래서 `design-system-color`, `design-system-spacing`, `design-system-shape`, `design-system-typography` 같은 Skill을 만들면서 일부러 user-invocable: false를 넣었습니다. 이 글은 왜 그렇게 했는지, 그리고 그 선택이 디자인 시스템을 수정하거나 확장할 때 어떤 차이를 만들었..

들어가며Claude Code를 쓰다 보면 생각보다 자주 반복되는 작업이 있습니다. 그중 하나가 바로 커밋 메시지 정리였습니다. 변경 내용을 보고 Conventional Commits 형식으로 적당한 메시지를 떠올리는 일은 어렵지는 않지만, 맥락을 한 번 더 읽고 정리해야 해서 은근히 흐름을 끊었습니다.그래서 저는 이 작업을 아예 Claude Code Skill로 분리해 봤습니다. 이번 글은 제가 만든 recommend-commit-message 스킬의 구조를 기준으로, 어떤 문제를 해결하려고 했는지, 어떻게 규칙을 설계했는지, 실제로 어떤 식으로 활용했는지를 공유하는 기록입니다.참고로 이 스킬은 GitHub에도 공개해뒀습니다. 글을 읽다가 직접 구조를 보고 싶다면 recommend-commit-messa..

들어가며Skills를 만들어보려고 SKILL.md를 처음 열면 바로 질문이 생긴다. frontmatter에는 어떤 필드를 쓸 수 있는가? description은 어떻게 쓰는 게 좋은가? Claude가 Skill을 자동으로 실행하지 않도록 막을 수 있는가? 파일을 어디에 두어야 팀 전체에 공유되는가?이 글은 그 질문들에 답한다. SKILL.md의 파일 구조, frontmatter 각 필드의 의미와 쓰임새, Skill을 어디에 저장하느냐에 따라 달라지는 적용 범위, 인수를 넘기고 시스템 변수를 활용하는 방법까지 — Skills를 설정하고 제어하는 데 필요한 내용을 정리했다.Skill이 동작하는 방식Skill의 핵심은 두 단계 로딩이다. 항상 모든 내용을 메모리에 올리는 게 아니라, 필요할 때만 가져온다. C..

들어가며Claude API를 처음 사용할 때 대부분의 개발자는 시스템 프롬프트에 배경지식을 쭉 적어 넣습니다. "너는 PDF 전처리 전문가야. 이 라이브러리를 쓰고, 이런 순서로 처리해야 해…" 같은 식으로요. 이 방법은 처음엔 잘 동작하지만, 결국 한계가 옵니다.지식이 많아질수록 프롬프트는 길어지고, 길어진 프롬프트는 컨텍스트 윈도우를 잠식합니다. 게다가 여러 프로젝트에서 같은 내용을 복붙하다 보면 관리도 엉망이 되죠.Agent Skills는 이 문제를 해결하기 위해 Anthropic이 설계한 구조입니다. 한 번 만들어두면 Claude가 필요할 때 알아서 꺼내 씁니다.Agent Skills가 뭔가요?Agent Skills는 Claude에게 도메인 특화 지식을 제공하는 파일 시스템 기반 모듈입니다. 쉽게..