글

처음 읽는다면

설정의 시작부터 막힌 문제, 도구에 드는 비용까지.

최근 보완: 2026-09-23 · 위 핵심 글 4편. 점검 순서와 관련 글을 보완했습니다. 실측·코드 분석·가정 계산은 구분해 표시합니다.

Claude Code 디자인 스킬 Hallmark, 규칙 위반을 어디까지 막을까

이미지
Claude Code 디자인 스킬 Hallmark는 문서 지시와 실제 검사를 한 폴더에 묶었지만, 규칙 위반을 전부 막지는 않는다. 로컬 린터가 종료 코드 1을 내는 경우는 FAIL이나 미해결 REFLEX가 남았을 때다. 2026-11-09에 커밋 407fa689 기준으로 공식 문서를 읽고 격리 사본에서 직접 실행해 확인했다. Floor 등급 항목도 판정이 WARN이면 종료 코드를 바꾸지 않는다. Claude Code 디자인 스킬은 어디까지 코드로 막는가 스킬 파일을 폴더에 넣어도 저장이나 배포가 자동으로 잠기지는 않는다. 그래서 모델에게 읽히는 지시와 스크립트가 잡는 항목부터 나눠 봐야 한다. Hallmark 공식 README(2026-11-09 확인)는 Claude Code, Codex, Cursor, OpenCode용 디자인 스킬이라고 소개한다. 사전 확인, 테마 선택, 히어로 우선 제작, 렌더 린트, 별도 검토가 문서에 적힌 작업 순서다. 규칙 문서 gates.md (2026-11-09 확인)는 심각도와 검사 방식을 따로 나눈다. 심각도는 면제 불가인 Floor, 근거를 적으면 면제되는 Reflex, 미세 완성도인 Finish, 별도 장부인 Ledger다. 검사 방식은 정적(M), 렌더(R), 판단(J)과 그 조합이다. 따라서 Floor는 스크립트, Finish는 사람이라고 짝지으면 틀린다. 같은 Floor 안에도 sloplint.mjs 가 잡는 항목, sloplint-render.mjs 가 재는 항목, 모델에게 내리는 지시가 섞여 있다. 그림의 네 단계 중 스크립트로 도는 것은 정적 검사와 렌더 검사뿐이고, 나머지는 문서 지시로 남는다. 정적 검사와 렌더 검사는 무엇을 잡았나 스킬 폴더를 샌드박스 프로젝트의 .claude/skills/hallmark 로 복사해 직접 실행해 봤다. 모델 호출은 0회다. 환경은 Node v26.10.0 , Chrome 157.0.8103.38 , puppeteer-core@25.16.0 이다. 시험용...

Claude Code 컨텍스트, 대형 템플릿 복사하면 무엇이 먼저 로드될까

이미지
에이전트 49개와 스킬 74개가 든 템플릿을 복사해도 정의 파일 본문이 첫 대화에 전부 들어오지는 않는다. 기본 설정으로 프로젝트 루트에서 새 세션을 열면 루트 지침과 @ 참조 파일, 이름·설명 목록, 시작 훅 출력이 먼저 문맥 재료가 된다. 공식 문서와 소스는 2026-11-09 KST에 확인했다. 본문은 호출할 때 읽히고, 이 커밋에서 시작 단계에 준비되는 정적 재료는 34,883바이트다. Claude Code 컨텍스트에 처음부터 들어오는 것은 무엇인가 남의 .claude 폴더와 CLAUDE.md 를 내 저장소에 복사하면 시작 문맥은 얼마나 커질까. 파일이 첫 질문부터 다 읽히는지, 부를 때만 읽히는지부터 나눠야 한다. 사례는 Donchitos의 Claude Code Game Studios 저장소다. 고정 커밋 05ad7c8a5b8aa2aa86bbd3439ae7cf7295cac418 (2026-10-19 커밋)을 shallow clone해 파일을 셌다. README와 실제 파일 모두 에이전트 정의 49개, SKILL.md 74개였다. 정의 파일 원문은 에이전트 457,813바이트, 스킬 1,021,536바이트다. 이 1.4메가바이트가 넘는 텍스트가 세션마다 들어가지는 않는다. 시작 때 준비되는 재료와 호출 때 읽히는 본문은 따로 봐야 한다. 세션이 열릴 때는 본문 없이 지침과 이름·설명 목록이 먼저 준비되고, 본문은 작업을 고른 뒤에 로드된다. 공식 문서와 소스로 확인한 로딩 시점 로딩 시점은 Claude Code 공식 문서에 나뉘어 있다. 「How Claude remembers your project」는 작업 디렉터리의 CLAUDE.md 를 시작할 때 읽고, @경로 로 가져온 파일 내용도 함께 확장한다고 설명한다. 「Extend Claude with skills」와 「Create custom subagents」에 따르면 이름·설명은 선택용 목록으로 먼저 들어간다. 본문은 호출하거나 실행할 때 로드된다. 소스는 Bun 1.4.4 스...

claude-mem 설치 전 소스 감사: 수집 범위와 외부 전송 경로

이미지
claude-mem은 요약문만 남기는 도구가 아니다. 프롬프트와 필터를 거친 도구 입출력을 로컬 SQLite에 저장하고, 별도 관찰 모델로 보내 기억을 만든다. Claude Code 기본 훅과 로컬 worker 기준이며, 커밋 6c8ef7e (버전 15.12.1 )의 소스와 격리 실행 결과를 2026-11-09 KST에 확인했다. 로컬 DB를 쓰더라도 요약 전 텍스트는 관찰 모델로 나가고, 자동 비밀정보 가림은 기본 꺼짐이며, 제거 명령은 데이터 폴더를 남긴다. claude-mem은 무엇을 수집하는가 세션 기억 도구라면 로컬 요약본만 남는다고 기대하기 쉽다. 이 소스는 그렇게 동작하지 않는다. 수집 지점부터 넓다. plugin/hooks/hooks.json 은 프롬프트 제출, 도구 호출 전후, 세션 종료 등에 훅을 건다. 실패한 도구 호출도 PostToolUseFailure 의 * 매처로 수집 경로에 들어오고, 그 뒤에 제외 필터가 적용된다. 요약 전 내용도 저장된다. 사용자 요청은 태그 제거 후 user_prompts 의 prompt_text 에 들어간다. toolUseId 가 있는 도구 호출은 tool_uses 의 tool_input , tool_response 열에 각 64 KiB 한도로 남는다. 응답 수집은 문서와 코드가 다르다. 공식 문서 private-tags.mdx 는 Claude 응답을 수집하지 않는다고 적는다. 그런데 summarize.ts 의 Stop 구현은 last_assistant_message 를 쓰고, 비어 있으면 트랜스크립트에서 마지막 응답을 읽는다. 이미지와 산출물 복사도 기본 켜짐이다. 이미지는 데이터 폴더의 media-v1 에 저장되고, 조건에 맞는 생성 문서는 ~/.claude-mem/deliverables/<project>/ 로 복사되는 경로가 있다. 사용자 입력과 도구 결과는 제외·가림을 거쳐 로컬 원문 테이블에 먼저 저장되고, 관찰 모델이 만든 기억은 같은 SQLite의 다른 테이블에 쌓여...

AGENTS.md 보안, 남의 저장소에서 에이전트를 켜기 전 점검법

이미지
남이 만든 저장소에서 코딩 에이전트를 켜면 내가 입력하지 않은 지침이 문맥에 먼저 들어간다. Codex와 Claude Code가 시작할 때 정해진 경로의 지침 파일을 찾는 조건에서 그렇다. 공식 문서와 실험은 모두 2026-11-09 KST에 확인했다. 실행 전에 소스 코드뿐 아니라 지침 파일과 훅, MCP 설정 목록을 먼저 뽑아 읽어야 한다. AGENTS.md 자동 로딩은 언제 일어나는가 왜 프롬프트에 없던 규칙이 응답에 따라붙을까. 에이전트는 세션을 시작할 때 정해진 경로의 파일을 찾아 문맥에 합치기 때문이다. OpenAI의 Custom instructions with AGENTS.md 문서를 보면 Codex는 ~/.codex 의 전역 지침에 이어 프로젝트 루트부터 현재 작업 디렉터리까지 내려간다. 디렉터리마다 AGENTS.override.md , AGENTS.md , project_doc_fallback_filenames 에 지정한 이름 순으로 찾아 한 파일만 포함한다. 합친 크기가 project_doc_max_bytes 기본값 32 KiB에 도달하면 추가를 멈춘다. 현재 디렉터리까지의 경로만 보므로 하위 폴더 전체를 처음부터 읽지는 않는다. 실제로 반영되는지 macOS arm64의 codex-cli 0.166.0 으로 시험했다. 프로젝트 AGENTS.md 가 없는 새 Git 저장소에서 도구를 쓰지 말라는 프롬프트로 아래 명령을 실행했다. codex --no-daemon --ask-for-approval never \ -c 'log_dir="<폴더>/logs"' \ -c 'sqlite_home="<폴더>/state"' \ -c 'history.persistence="none"' \ -c 'web_search="disabled"' \ exec --ignore-user-confi...

Worktrunk는 git worktree보다 명령을 얼마나 줄일까

이미지
Worktrunk는 git worktree 를 대체하는 격리 기술이 아니고, 브랜치 이름으로 작업 폴더의 생성·이동·상태 확인·병합·정리를 묶는 CLI다. 기존 커밋 하나를 main 에 fast-forward하고 정리하는 절차에서 셸 래퍼를 켠 Worktrunk는 6명령, 기본 Git은 9명령이었다. 2026-11-09 macOS arm64에서 Worktrunk v0.81.0 , Git 2.50.1 을 격리 실행한 결과다. Worktrunk가 덜어 주는 것은 브랜치 이름과 경로를 오가는 이동과 정리 절차다. git worktree와 Worktrunk는 무엇이 다른가 작업 폴더 분리는 기본 Git이 이미 한다. Git 공식 git-worktree 매뉴얼(2026-11-09 확인)은 git worktree add 로 연결된 작업 디렉터리를 만들고 list , remove , prune 으로 관리한다고 설명한다. 두 도구 모두 모델의 파일 접근이나 네트워크를 막는 보안 샌드박스는 아니다. 차이는 이동 단위다. Worktrunk v0.81.0 릴리스 참조 문서(2026-11-09 확인)에 따르면 wt switch 는 브랜치에 대응하는 작업 폴더를 찾거나 만든다. 같은 폴더에서 브랜치만 바꾸는 git switch 와 다르다. 에이전트마다 브랜치별 폴더를 나눠 주며 경로를 직접 따라가는 일이 번거롭다면 검토할 만하다. 같은 작업에서 명령 수는 얼마나 달랐나 부모 커밋을 main , 릴리스 태그 v0.81.0 을 feature 로 두고 양쪽에서 생성, 목록, 이동, 병합, 정리를 직접 실행해 봤다. Worktrunk는 일회성 자식 Bash에서 셸 래퍼를 켠 뒤 아래 6명령을 썼다. wt switch --create feature --base v0.81.0 --no-hooks wt list wt switch main --no-hooks wt switch feature --no-hooks wt merge main --no-commit --no-rebase -...

agent-browser 설치 후 클릭 결과는 전체 snapshot으로 확인한다

이미지
agent-browser 는 접근성 트리 snapshot과 @e 참조로 브라우저를 조작하는 CLI다. macOS arm64와 Node v26.10.0 에서 agent-browser@0.41.2 를 격리 폴더에 설치하고, 외부 자원이 없는 로컬 HTML 한 페이지에서 클릭 뒤 snapshot 재확인까지 검증했다. 문서 확인과 실험은 2026-11-09 KST에 했다. 이 테스트 페이지에서 전체 snapshot은 원시 HTML보다 74.19% 작으면서 -i 에 빠진 상태 문구를 담아 행동 뒤 검증에 썼다. agent-browser 설치와 snapshot으로 확인할 것 원시 HTML을 통째로 넘기면 조작과 무관한 마크업까지 함께 읽힌다. 반대로 조작 대상만 추리면 클릭 뒤 상태가 바뀌었는지 놓칠 수 있다. 그렇다면 시스템 설정을 건드리지 않고 설치해 열기부터 종료까지 돌릴 수 있을까. 출력 바이트는 원시 HTML과 얼마나 다를까. 공식 문서가 설명하는 작동 방식 vercel-labs agent-browser 저장소의 README와 문서(릴리스 태그 v0.41.2 , 2026-11-09 KST 확인)를 기준으로 했다. 문서에 따르면 Rust CLI는 첫 명령에서 백그라운드 데몬을 띄운다. 데몬은 Chrome DevTools Protocol로 브라우저를 제어하고, 명령 사이에도 브라우저를 열어 둔다. Snapshots 문서는 snapshot 이 접근성 트리를 짧은 텍스트와 참조로 돌려주고, 이후 click @e2 처럼 조작한다고 설명한다. 요소가 교체되거나 페이지를 이동하면 ref가 무효화될 수 있다고도 적었다. 이번 실험 출력에서 참조는 [ref=e2] 형태로 나왔다. 브라우저 설치 위치는 cli/src/install.rs 의 get_browsers_dir() 가 정한다. 이 함수는 std::env::home_dir() 아래 .agent-browser/browsers 를 쓴다. Rust 공식 문서에 따르면 home_dir() 는 Unix에서 H...

Claude Code 비밀값 노출 원인과 로컬 설정 파일 점검법

이미지
Claude Code CLI에서 Bash 명령을 다시 묻지 않기로 승인하면 허용 규칙이 프로젝트의 .claude/settings.local.json 에 문자열로 저장된다. 규칙에 토큰이나 비밀번호가 평문으로 들어 있으면 값도 함께 남고, 이 파일을 공개 저장소에 커밋해 푸시하면 값도 공개된다. 공식 문서와 Apiiro 보고서는 2026-11-09 KST에 확인했고, Git 동작은 더미 파일로 직접 실행해 봤다. 영구 승인이 모든 명령을 덤프하지는 않지만, 비밀값이 든 정확한 명령을 승인하고 이 파일이 Git에 커밋되면 평문이 저장소에 남는다. Claude Code 비밀값 노출은 승인 규칙에서 어떻게 시작될까 다시 묻지 않기를 고른 승인은 어디에 남을까. Anthropic의 Configure permissions 공식 문서는 Bash 영구 승인이 저장소와 명령별로 지속된다고 설명한다. CLI 기준 저장 위치는 .claude/settings.local.json 이고, 규칙 형식은 Tool 또는 Tool(specifier) 다. Bash 규칙에 * 가 없으면 정확한 명령 전체를 허용한다. * 가 있으면 그 자리에 어떤 텍스트가 와도 허용한다. 그래서 아무 명령이나 한 번 승인하면 비밀값이 저장된다는 말은 과장이다. 반대로 헤더나 환경변수 할당에 실제 토큰을 넣은 명령을 정확한 규칙으로 승인하면, 그 문자열이 permissions.allow 에 평문으로 들어간다고 본다. 비밀값이 든 명령은 지속 승인을 거쳐 로컬 설정의 허용 규칙이 된다. 공개 저장소까지 이어지는 것은 Git 커밋과 공개 저장소 푸시가 겹칠 때뿐이다. 공개 저장소에서는 얼마나 발견됐을까 Apiiro의 보고서 Coding Agents Are Leaking Your Secrets to GitHub는 2026-11-01부터 03일까지 공개 GitHub 기본 브랜치를 읽기 전용으로 검색한 결과다. 아래 수치는 모두 Apiiro의 분류 결과이며, 이번에 다시 조사하지 않았다. 공개 .cl...