Claude Code의 /init은

리포지토리를 조사하여 CLAUDE.md를 한 장 만드는 명령어입니다.

환경 변수 CLAUDE_CODE_NEW_INIT=1

을 설정하고 실행하면, 이것이 완전히 다른 것으로 바뀝니다.

CLAUDE.md에 더해 .claude/rules/

·스킬(skills)·훅(hooks)까지, 주요 지점마다 승인을 받으면서 한꺼번에 셋업하는 대화형 플로우(dialogue flow)로 변경되었습니다.

Claude Code v2.1.220에서 실제로 구동하여 생성물 내부까지 확인했으므로 보고합니다.

이 플래그의 존재는 Claude Code의 바이너리 내 문자열을 통해 확인한 것이며, 일본어권에서 소개된 것은 아직 보지 못했습니다.

검증 환경과 준비

대상은 개인 개발 중인 Python 리포지토리(swing-copilot)입니다.

평소에는 CLAUDE.md·AGENTS.md·.claude/

(rules·스킬·훅)을 일일이 수동으로 정비하여 운용하고 있는 리포지토리입니다.

이번에는 "설정이 아무것도 없는 상태"에서 무엇을 만들어내는지 보고 싶었기에, 클린한 clone 상태에서 그것들을 삭제하고 시도했습니다.

git clone <원래 리포지토리> ~/work/newinit-test/swing-copilot
cd ~/work/newinit-test/swing-copilot
rm -rf CLAUDE.md AGENTS.md .claude
...

기동 후 /init을 실행하기만 하면 됩니다.

참고로 working tree에서는 삭제했지만, git 히스토리에는 구 설정이 남아 있습니다.

이 상태가 나중에 흥미로운 전개를 만들어냅니다.

실행 흐름

먼저, 어떤 CLAUDE.md를 만들지 묻습니다.

Which CLAUDE.md files should /init set up?
❯ 1. Project CLAUDE.md
2. Personal CLAUDE.local.md
...

Project는 팀에서 공유하는 커밋 대상, Personal은 gitignore 되는 개인용이라는 구분입니다.

"Let Claude decide"를 선택하면 이후의 질문을 생략하고 일괄 제안까지 진행되도록 설계되어 있습니다.

이번에는 Project를 선택했습니다.

이어서 스킬과 훅도 만들지 묻습니다.

기존 /init과의 가장 큰 차이점은 이 부분입니다.

Also set up skills and hooks?
❯ 1. Skills + hooks
2. Skills only
...

Skills + hooks를 선택하자, 조사를 위한 서브 에이전트(sub-agent)가 코드베이스를 읽기 시작했습니다.

이번 리포지토리 기준으로 4분 31초가 소요되었습니다.

놀라운 것은 그다음이었습니다.

조사를 마친 에이전트가 git 히스토리로부터 "기존 .claude 세트가 삭제되었음"을 감지하고, 어떻게 처리할지 물어옵니다.

삭제된 기존 .claude 셋업(CLAUDE.md / AGENTS.md / rules / hooks / skills)
은 어떻게 처리할까요?
❯ 1. git에서 복원하여 개선
...

검증을 위해 "제로 베이스에서 다시 쓰기"를 선택했습니다.

그러자 무엇을 어디까지 만들지에 대한 제안이 제시되었고, 승인 선택지에는 "제외한 스킬도 전부 포함", "Drop the hooks", "Drop the rules"와 같은 조정 옵션들이 나열됩니다.

승인하자, 4체의 서브 에이전트가 병렬로 rules·스킬·훅을 쓰기 시작했습니다.

단순히 생성하고 끝나는 것이 아닙니다.

작성된 훅에 대해 임시 파일을 만들어 발화(trigger)를 확인하는 테스트를 20케이스 실행하였고, settings.json은 jq로 검증했습니다.

마지막으로 성과물 목록과 QA findings(할 수 있었던 것·할 수 없었던 것), 추가 최적화 후보까지 정리하여 보고합니다.

여기까지 총 23분 15초가 걸렸습니다.

생성된 것

삭제 전의 수동 자산과 생성된 자산의 비교입니다.

훅은 안전과 관련된 부분이므로 동작을 엄격히 준수하여 작성되었으며, 결과적으로 구 버전과 바이트 단위로 동일하게 수렴했습니다.

.claude/rules/

압축 또한 사라졌으며, 사라진 것은 범용적인 Python 일반론이었고, "이 규칙을 완화하지 마라"라는 보호 계약은 남아 있습니다.

CLAUDE.md의 내용도, "완료 게이트(completion gate)는 just verify여야 하며 just test가 아니다"와 같이, 실제로 사고가 나기 쉬운 포인트를 짚어낸 기술이 되어 있었습니다.

초안(draft)으로서는 충분히 우수합니다. 다만 내용에 대한 리뷰는 필수이며, 검증 없이 그대로 커밋할 만한 종류의 것은 아닙니다.

rules와 후크(hook)의 메커니즘 자체는 이전 기사에서 해설했습니다.

새로운 /init의 설계

지금까지의 생성물은 어떤 메커니즘을 통해 나온 것일까요.

새로운 플로우의 실체는 /init에 포함된 약 2만 자, 9 Phase 구성의 프롬프트 템플릿(prompt template)입니다.

세션의 트랜스크립트(transcript)를 통해 전문을 확인했습니다.

서두에는 다음과 같이 적혀 있습니다.

CLAUDE.md is loaded into every Claude Code session, so it must be concise — only include what Claude would get wrong without it.

CLAUDE.md는 매 세션마다 로드되므로 간결하게, "그것이 없으면 Claude가 틀릴 내용"만을 작성하라는 방침입니다.

생성된 CLAUDE.md가 52행 안에 들어왔던 것은 이 지시의 결과임을 알 수 있습니다.

설계로서 짚어두어야 할 점 3가지를 꼽겠습니다.

• 기존의 CLAUDE.md가 있는 경우의 분기(branch)도 설계되어 있음 (Review and improve / Leave it / Start fresh)
• 처음 사용하는 사용자를 위해 CLAUDE.md, 스킬(skill), 후크(hook)가 무엇인지에 대한 설명을 처음에 제공
• 조사 대상에는 .cursorrules, .clinerules, .windsurf/rules 등 다른 AI 코딩 도구의 설정 파일도 포함됨

즉, "기존 리포지토리(repo)의 재정비"와 "타 도구로부터의 이행(migration)" 모두를 내다본 설계입니다.

다만, 이 3가지는 템플릿상의 설계로서 확인한 것이며, 이번 실행에서는 등장하지 않았습니다 (다음 절).

주의사항 및 요약

테스트할 때의 주의사항입니다.

• 실험적인 플래그(flag)이므로, 향후 버전에서 동작이 변하거나 없어질 가능성이 있습니다.
• 생성 직후의 세션에서는 후크(hook)가 발화하지 않습니다. 기동 시 settings.json이 존재하지 않았기 때문이며, QA findings 자체에서도 "/hooks를 한 번 열거나 세션을 재시작하면 유효해집니다"라고 명시했습니다.
• 기존 CLAUDE.md가 있는 경우의 분기와 타 도구 설정의 가져오기(import)는 미검증 상태입니다 (템플릿상의 설계로서 확인했을 뿐입니다).

누구에게 적합하냐고 묻는다면, CLAUDE.md만으로 운용해 온 기존 리포지토리의 재정비에 가장 효과적일 것이라고 생각합니다.

스킬이나 후크가 편리하다는 것은 알고 있어도, 무엇을 어떻게 만들어야 할지 몰라 뒤로 미루기 쉽습니다.

리포지토리를 조사한 뒤 초안 세트를 생성하게 하고, 이를 리뷰하며 키워 나가는 방식으로 접근할 수 있습니다.

23분이 소요되었지만, 생성물은 이후 계속 사용할 것이므로 첫 투자로서는 문제없다고 느꼈습니다.

환경의 점검(inventory)을 /doctor에 맡기는 이야기도 이전에 썼습니다.

정비를 맡기는 입구로서 함께 참고해 보시기 바랍니다.

요약하자면, CLAUDE_CODE_NEW_INIT=1을 통해 /init은 CLAUDE.md 생성부터 리포지토리 분석이 포함된 풀 셋업(full setup)으로 바뀝니다.

생성물은 양질이지만 리뷰를 전제로 하며, 기존 리포지토리의 재정비에 가장 적합합니다.

X를 팔로우해 주시면 감사하겠습니다!

AI 주도 개발(특히 Claude Code)의 노하우나 팁(Tips)을 자주 발신하고 있습니다!

Discussion