Add Claude Code practical posts

Author: k4nul

_posts/2026-05-06-claude-code-as-operating-structure.md

@@ -0,0 +1,139 @@
+---
+layout: single
+description: "Claude Code의 CLAUDE.md에 무엇을 넣고 무엇을 rules, skills, settings로 내려야 하는지 정리한 글."
+title: "Claude Code 실전 활용 02. CLAUDE.md는 어디까지 써야 하는가"
+lang: ko
+translation_key: how-far-should-claude-md-go
+date: 2026-05-07 00:00:00 +0900
+section: development
+topic_key: ai
+categories: AI
+tags: [ai, claude-code, claude-md, instructions, harness-engineering]
+author_profile: false
+sidebar:
+  nav: "sections"
+search: false
+---
+
+## 요약
+
+`CLAUDE.md`는 Claude Code가 매 세션마다 들고 시작하는 프로젝트 지시 파일이다. 그래서 여기에 넣을 내용은 "가끔 필요한 절차"가 아니라 "매번 알아야 하는 짧고 검증 가능한 기준"이어야 한다.
+
+이 글의 결론은 단순하다. `CLAUDE.md`는 운영 문서 전체가 아니라 진입점이다. 긴 절차는 skills로, 경로별 규칙은 `.claude/rules/`로, 강제 경계는 settings와 permissions로 내려야 문맥을 덜 낭비한다.
+
+## 문서 정보
+
+- 작성일: 2026-04-24
+- 검증 기준일: 2026-04-24
+- 문서 성격: analysis
+- 테스트 환경: 실행 테스트 없음. Anthropic Claude Code 공식 문서를 바탕으로 한 구조 정리.
+- 테스트 버전: Claude Code 공식 문서 2026-04-24 확인본. 로컬 Claude Code CLI 버전은 확인하지 않음.
+
+## 문제 정의
+
+Claude Code를 쓰기 시작하면 `CLAUDE.md`에 규칙을 계속 추가하고 싶어진다. 빌드 명령, 테스트 명령, 코드 스타일, 배포 절차, 리뷰 체크리스트, 팀 운영 원칙이 한 파일에 쌓인다.
+
+문제는 `CLAUDE.md`가 길어질수록 중요한 규칙도 덜 선명해질 수 있다는 점이다. 이 글은 `CLAUDE.md`에 남길 내용과 다른 계층으로 내릴 내용을 나누는 기준을 제시한다.
+
+## 확인된 사실
+
+공식 문서 기준: Claude Code 세션은 fresh context window로 시작하고, `CLAUDE.md` 파일과 auto memory는 대화 시작 시 로드된다. 문서는 이 둘이 enforced configuration이 아니라 context라고 설명한다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: `CLAUDE.md`는 프로젝트, 사용자, 조직, 로컬 범위에 둘 수 있다. 프로젝트 지시는 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md`에 둘 수 있고, 개인 로컬 지시는 `CLAUDE.local.md`에 둘 수 있다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: `CLAUDE.md`는 세션 시작 시 context window에 들어가며, 문서는 파일당 200줄 이하를 목표로 하라고 권장한다. 긴 절차나 코드베이스 일부에만 필요한 규칙은 path-scoped rule이나 skill로 옮기는 것이 권장된다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: `CLAUDE.md`는 `@path/to/import` 문법으로 다른 파일을 import할 수 있다. import된 파일도 launch 시 context에 확장되어 들어가며, recursive import는 최대 5단계까지 허용된다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: settings 문서는 `CLAUDE.md` 같은 memory files와 JSON settings files를 구분한다. settings files는 permissions, environment variables, tool behavior를 설정한다. 근거: [Anthropic, Claude Code settings](https://code.claude.com/docs/en/settings)
+
+## 직접 재현한 결과
+
+직접 재현 없음: 이 글은 실제 저장소에서 `CLAUDE.md` 길이를 바꿔가며 Claude Code의 작업 품질을 측정한 실험 글이 아니다.
+
+검증한 것은 2026-04-24 기준 공식 문서의 구조다. 아래 기준은 공식 문서가 설명한 로딩 방식과 이 블로그의 하네스 엔지니어링 관점을 연결한 운영 판단이다.
+
+## 해석 / 의견
+
+### 넣을 것과 빼야 할 것
+
+내 판단으로는 `CLAUDE.md`에는 아래 네 가지 정도만 남기는 편이 안정적이다.
+
+| 분류 | `CLAUDE.md`에 적합한 내용 | 다른 계층으로 내릴 내용 |
+| --- | --- | --- |
+| 프로젝트 정체성 | 저장소 목적, 주요 경로, 기술 스택 | 긴 아키텍처 설명 전문 |
+| 기본 명령 | 자주 쓰는 build, test, lint 명령 | 상황별 디버깅 절차 |
+| 반복 규칙 | 매번 지켜야 하는 코드 스타일, 리뷰 기준 | 특정 디렉터리 전용 규칙 |
+| 완료 기준 | 검증 보고 형식, 미실행 검증 표시 | 자동 실행해야 하는 검사 |
+
+의견: `CLAUDE.md`는 "Claude가 항상 알아야 하는 사실"에 가깝고, skill은 "필요할 때 실행할 절차"에 가깝다. 같은 내용을 넣더라도 위치가 바뀌면 문맥 비용과 유지보수 방식이 달라진다.
+
+### 최소 템플릿
+
+작은 프로젝트라면 아래 정도에서 시작해도 충분하다.
+
+```md
+# CLAUDE.md
+
+## Project
+
+- This repository is ...
+- Main application code lives in ...
+- Tests live in ...
+
+## Commands
+
+- Install: ...
+- Test: ...
+- Lint: ...
+
+## Working Rules
+
+- Keep changes scoped to the requested task.
+- Do not edit generated files unless explicitly requested.
+- Report tests run and tests not run separately.
+
+## References
+
+- Detailed release workflow: use `/release-checklist`.
+- Path-specific frontend rules live in `.claude/rules/frontend.md`.
+```
+
+의견: 중요한 것은 템플릿 자체가 아니라 길이와 책임이다. `CLAUDE.md`가 커지면 먼저 "이 문장이 매 세션마다 필요한가"를 물어야 한다.
+
+### import는 복사가 아니라 비용 이전이다
+
+`@docs/guide.md`처럼 import를 쓰면 문서를 복사하지 않아도 되어 유지보수는 편해진다. 하지만 공식 문서 기준으로 import된 파일도 launch 시 context에 들어간다. 그래서 import는 공짜 압축이 아니다.
+
+의견: import는 source of truth를 한 곳에 두는 데 좋다. 반면 긴 reference를 문맥에서 숨기기 위한 도구로 보면 안 된다. 긴 문서를 필요할 때만 읽게 하려면 skill, MCP, 파일 참조 같은 다른 방법을 검토하는 편이 낫다.
+
+### `CLAUDE.local.md`는 개인 설정에만 쓴다
+
+`CLAUDE.local.md`는 로컬 개인 지시를 담을 수 있지만, 팀 전체 기준을 여기에 두면 다른 사람에게 재현되지 않는다.
+
+의견: `CLAUDE.local.md`에는 개인 sandbox URL, 선호 test data, 로컬 도구 경로처럼 공유하면 안 되거나 공유할 필요가 없는 내용만 두는 편이 낫다. 팀 규칙은 version control에 올라가는 `CLAUDE.md`나 `.claude/rules/`로 옮겨야 한다.
+
+### 줄일 때의 기준
+
+`CLAUDE.md`가 길어졌다면 아래 순서로 줄인다.
+
+1. 특정 경로나 파일 유형에만 적용되는 내용은 `.claude/rules/`로 옮긴다.
+2. 여러 단계 절차는 skill로 옮긴다.
+3. 금지해야 하는 파일 접근이나 명령은 settings와 permissions로 옮긴다.
+4. 사람을 위한 배경 설명은 `docs/`로 옮기고, `CLAUDE.md`에는 위치만 남긴다.
+
+의견: 좋은 `CLAUDE.md`는 친절한 매뉴얼이 아니라 작은 운영 지도다. Claude Code가 어디를 봐야 하는지 알려 주되, 모든 내용을 매번 들고 시작하게 만들 필요는 없다.
+
+## 한계와 예외
+
+이 글은 2026-04-24 기준 공식 문서를 바탕으로 한 운영 기준이다. Claude Code의 파일 로딩 방식, 권장 줄 수, settings 키는 이후 바뀔 수 있다.
+
+직접 실행 테스트를 하지 않았으므로, 특정 버전의 CLI 화면이나 `/init`, `/memory`, import approval 동작은 검증 범위 밖이다.
+
+작은 개인 프로젝트에서는 `CLAUDE.md` 하나에 조금 더 많은 내용을 넣어도 운영 비용이 크지 않을 수 있다. 반대로 모노레포나 팀 저장소에서는 계층 분리가 더 일찍 필요해질 수 있다.
+
+## 참고자료
+
+- Anthropic, [How Claude remembers your project](https://code.claude.com/docs/en/memory)
+- Anthropic, [Claude Code settings](https://code.claude.com/docs/en/settings)
+- Anthropic, [Extend Claude Code](https://code.claude.com/docs/en/features-overview)

_posts/2026-05-07-how-far-should-claude-md-go.md

@@ -0,0 +1,122 @@
+---
+layout: single
+description: "AGENTS.md를 이미 쓰는 저장소에서 Claude Code의 CLAUDE.md를 중복 없이 연결하는 방법."
+title: "Claude Code 실전 활용 03. AGENTS.md가 있는 저장소에서 Claude Code를 함께 쓰는 법"
+lang: ko
+translation_key: use-claude-code-with-agents-md
+date: 2026-05-08 00:00:00 +0900
+section: development
+topic_key: ai
+categories: AI
+tags: [ai, claude-code, agents-md, claude-md, codex, harness-engineering]
+author_profile: false
+sidebar:
+  nav: "sections"
+search: false
+---
+
+## 요약
+
+이미 `AGENTS.md`를 쓰는 저장소에서 Claude Code를 도입할 때 같은 규칙을 `CLAUDE.md`에 복사하면 지시가 중복된다. 중복은 길이 문제만 만들지 않는다. 어느 파일이 기준인지도 흐리게 만든다.
+
+이 글은 `AGENTS.md`를 source of truth로 두고, `CLAUDE.md`는 import와 Claude Code 전용 보충 지시만 담는 방식을 제안한다.
+
+## 문서 정보
+
+- 작성일: 2026-04-24
+- 검증 기준일: 2026-04-24
+- 문서 성격: analysis
+- 테스트 환경: 실행 테스트 없음. Anthropic Claude Code 공식 문서와 OpenAI Codex 공식 문서를 바탕으로 한 병행 운영 정리.
+- 테스트 버전: Claude Code 공식 문서 2026-04-24 확인본, OpenAI Codex 공식 문서 2026-04-24 확인본. 로컬 CLI 버전은 확인하지 않음.
+
+## 문제 정의
+
+Codex, Claude Code, 다른 코딩 에이전트를 한 저장소에서 함께 쓰면 프로젝트 규칙 파일이 늘어난다. `AGENTS.md`에는 Codex용 규칙이 있고, Claude Code는 `CLAUDE.md`를 읽는다. 여기서 같은 내용을 양쪽에 복사하면 수정할 때마다 동기화 문제가 생긴다.
+
+이 글의 목표는 두 도구를 비교해 우열을 가리는 것이 아니다. 이미 있는 `AGENTS.md`를 낭비하지 않고 Claude Code와 함께 쓰는 얇은 연결 구조를 만드는 것이다.
+
+## 확인된 사실
+
+공식 문서 기준: Claude Code는 `AGENTS.md`가 아니라 `CLAUDE.md`를 읽는다. Anthropic 문서는 `AGENTS.md`를 이미 쓰는 저장소에서는 `CLAUDE.md`에서 `@AGENTS.md`를 import하고 Claude Code 전용 지시를 아래에 추가할 수 있다고 설명한다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: Claude Code의 `@path` import는 launch 시 context에 확장되어 들어간다. 상대 경로는 import를 포함한 파일 기준으로 해석된다. 근거: [Anthropic, How Claude remembers your project](https://code.claude.com/docs/en/memory)
+
+공식 문서 기준: Codex는 작업 전에 `AGENTS.md`를 읽고, global guidance와 project-specific overrides를 결합해 instruction chain을 만든다. 근거: [OpenAI, Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
+
+공식 문서 기준: Codex는 프로젝트 루트에서 실행 작업 디렉터리까지 내려오며 지시 파일을 결합하고, 기본 `project_doc_max_bytes` 한도는 32 KiB다. 근거: [OpenAI, Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
+
+## 직접 재현한 결과
+
+직접 재현 없음: 이 글은 같은 저장소에서 Codex와 Claude Code를 동시에 실행해 instruction chain을 비교한 실험 글이 아니다.
+
+검증한 것은 2026-04-24 기준 두 제품의 공식 문서다. 아래 구조는 문서에서 확인된 로딩 방식과 중복 지시를 줄이기 위한 운영 판단을 연결한 것이다.
+
+## 해석 / 의견
+
+### 기본 구조
+
+내 판단으로는 이미 `AGENTS.md`가 있는 저장소의 `CLAUDE.md`는 아래처럼 시작하는 편이 좋다.
+
+```md
+@AGENTS.md
+
+## Claude Code
+
+- 큰 변경은 먼저 계획과 검증 방법을 제안한다.
+- 완료 보고에는 변경 파일, 실행한 검증, 실행하지 못한 검증, 남은 위험을 분리한다.
+- Claude Code 전용 settings, hooks, skills는 `.claude/` 아래 문서를 기준으로 한다.
+```
+
+이 구조에서 `AGENTS.md`는 공통 프로젝트 규칙의 기준이고, `CLAUDE.md`는 Claude Code가 읽을 수 있게 연결하는 어댑터다.
+
+### 무엇을 어디에 둘 것인가
+
+| 내용 | 권장 위치 | 이유 |
+| --- | --- | --- |
+| 저장소 목적, 우선 확인 경로, 공통 리뷰 기준 | `AGENTS.md` | 여러 에이전트가 공유할 기준 |
+| Claude Code가 `AGENTS.md`를 읽게 하는 연결 | `CLAUDE.md` | Claude Code는 `CLAUDE.md`를 읽기 때문 |
+| Claude Code 전용 권한, hook, MCP 메모 | `CLAUDE.md` 또는 `.claude/` 문서 | 도구별 운영 차이를 분리하기 위함 |
+| 경로별 세부 규칙 | 가까운 `AGENTS.md` 또는 `.claude/rules/` | 작업 위치에 따라 필요한 규칙을 좁히기 위함 |
+| 반복 절차 | skill | 필요할 때만 로드하기 위함 |
+
+의견: 핵심은 "공통 규칙은 한 곳, 도구별 보충은 얇게"다. 같은 금지사항을 여러 파일에 반복하면 나중에 하나만 수정되어 충돌할 가능성이 커진다.
+
+### 이 블로그 저장소에 적용한다면
+
+이 저장소는 이미 루트 `AGENTS.md`와 `_posts/AGENTS.md`로 포스트 작성 규칙을 나누고 있다. Claude Code를 병행한다면 `CLAUDE.md`는 아래처럼 얇게 두는 편이 자연스럽다.
+
+```md
+@AGENTS.md
+
+## Claude Code
+
+- `_posts/` 글 작성과 수정은 `_posts/AGENTS.md`와 `docs/blog-style.md`를 먼저 확인한다.
+- 공식 문서로 확인한 사실, 직접 재현한 결과, 해석 / 의견을 섞지 않는다.
+- 시간에 민감한 내용은 검증 기준일을 본문에 남긴다.
+- 긴 계획은 `project-docs/plans/` 아래 문서를 기준으로 갱신한다.
+```
+
+의견: 이 예시는 `AGENTS.md` 내용을 복사하지 않는다. Claude Code에게 필요한 연결과 보충만 둔다.
+
+### 중복을 줄이는 점검표
+
+1. 같은 문장이 `AGENTS.md`와 `CLAUDE.md`에 반복되는가.
+2. 반복된다면 한쪽은 import나 참조로 바꿀 수 있는가.
+3. Claude Code 전용 내용인가, 모든 에이전트 공통 내용인가.
+4. 긴 절차라면 skill로 분리할 수 있는가.
+5. 금지해야 하는 행동이라면 자연어 지시보다 permissions나 hooks가 더 적절한가.
+
+의견: `CLAUDE.md`는 `AGENTS.md`의 번역본이 아니라 연결 파일에 가깝게 두는 편이 유지보수에 좋다.
+
+## 한계와 예외
+
+이 글은 2026-04-24 기준 공식 문서에 근거한다. Codex와 Claude Code의 지시 파일 로딩 방식은 제품 업데이트에 따라 바뀔 수 있다.
+
+`@AGENTS.md` import는 중복을 줄이지만, import된 파일도 Claude Code context에 들어간다. 긴 `AGENTS.md`를 import하면 문맥 비용도 함께 늘어난다.
+
+팀이 `AGENTS.md`와 `CLAUDE.md`를 완전히 다른 역할로 운영하기로 합의한 경우에는 이 글의 구조가 맞지 않을 수 있다. 다만 그런 경우에도 source of truth가 어디인지 문서화해야 한다.
+
+## 참고자료
+
+- Anthropic, [How Claude remembers your project](https://code.claude.com/docs/en/memory)
+- OpenAI, [Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md)