AI 도구 매일 노트 — 해고된 개발자의 기록

AI 코딩 스킬은 자산이다. 처음 몇 개는 그렇다. 그런데 수가 늘면 세금이 붙는다. 어느 스킬이 뜰지 예측이 안 되고, 도구 출력이 컨텍스트를 먹고, 모델이 바뀌면 쌓은 걸 전부 다시 만진다. 스킬을 관리하는 앱이 시장에 나온 게 그 신호다. 만들지 말라는 게 아니다. 만든 만큼 쳐내야 자산으로 남는다. 스킬은 자산으로 시작한다, 그런데 요즘 개발자들이 자기 .claude 디렉터리를 통째로 공개한다. TypeScript 교육자 Matt Pocock도 스킬 묶음을 GitHub에 올렸다. 제목이 “Skills for Real Engineers”이고, 소개가 “내 .claude 디렉터리에서 바로”다. skills.sh 같은 스킬 레지스트리도 생겼다. 스킬이 자산인 건 맞다. 손으로 반복하던 작업을 트리거 한 줄로 줄인다. 결과도 매번 일정해진다. 그래서 다들 쌓는다. 그런데 같은 GitHub에 묘한 게 같이 뜬다. 스킬을 “관리하고 동기화하고 정리”하는 데스크톱 앱이다. skills-manager는 Cursor·Claude Code·Codex 등 15개 넘는 도구의 스킬을 한곳에서 관리한다고 소개한다. 자산을 관리하는 전용 앱이 필요해졌다는 건, 그 자산이 관리 대상이 됐다는 뜻이다. 관리 대상은 곧 부담이다. 여기서 질문이 갈린다. AI 코딩 스킬은 많을수록 좋은가. 다음 중 하나라도 있나 비슷한 일을 하는 스킬이 둘 이상이라, 어느 게 뜰지 헷갈린 적이 있다. 스킬 하나를 고쳤더니 엉뚱한 데서 다른 게 어긋난 적이 있다. 내가 무슨 스킬을 만들어뒀는지, 목록을 열어봐야 기억나는 적이 있다. 셋 중 하나라도 해당되면 이미 부채 구간에 발을 걸친 것이다. 세 신호를 하나씩 본다. 신호 1 — 어느 스킬이 뜰지 예측이 안 된다 스킬이 늘면 비슷한 트리거를 여럿이 주장한다. “리뷰”라는 말에 코드 리뷰 스킬도 반응하고, 글 리뷰 스킬도 반응한다. 그러면 매 요청마다 “어느 스킬을 부를지” 판별하는 비용이 붙는다. 자동 라우팅 점...

MCP vs CLI — AI 코딩 에이전트 도구 연결, 둘 다 써보고 정리한 선택 기준 AI 코딩 에이전트에 도구를 붙이는 방식을 두고 MCP냐 CLI냐 하는 글이 늘었다. 나는 양쪽을 다 쓴다. 코드 검색은 MCP 서버로 하고, 시크릿 차단과 블로그 발행은 CLI 쪽에 맡긴다. 그런데 오늘 평소와 다른 디렉토리에서 세션을 열었다가, 늘 쓰던 MCP 서버가 조용히 빠져 있는 걸 발견했다. 에러 한 줄 없었다. 이 사건까지 겹치고 나서야 정리가 됐다 — 판단 기준은 도구의 모양이 아니라 “무엇을 통제해야 하는가”였다. 먼저 요약. 세션 안에서 반복되는 조회는 MCP가 이기고, 실행을 막거나 검증해야 하는 작업은 CLI가 이긴다. 그리고 내 환경에서 제일 잘 굴러가는 구조는 둘 중 하나를 고르는 대신, CLI 훅이 MCP 사용을 강제하는 조합이었다. 누가 읽으면 좋은가 Claude Code나 Codex에 MCP 서버를 몇 개 붙였는데, 컨텍스트만 커지고 체감 이득이 없던 적이 있다. 에이전트가 cat과 grep으로 코드를 통째로 읽어대서, 토큰 사용량이 신경 쓰인 적이 있다. .env 노출 같은 사고를 막고 싶은데, MCP 서버를 잘 고르면 될 거라고 기대한 적이 있다. 셋 다 내가 직접 겪은 일이다. 같은 상황이라면 아래 기준을 그대로 가져다 써도 될 것 같다. 내 환경에서 두 방식이 놓이는 자리 MCP(Model Context Protocol)는 에이전트가 세션 안에서 도구를 함수처럼 호출하는 연결 방식이고, CLI는 에이전트가 셸에서 명령을 실행하는 방식이다. 아래 표의 훅은 그 실행 앞뒤에 끼어드는 검사 스크립트를 말한다. 내 환경에서 실제로 돌아가는 작업을 연결 방식별로 나누면 이렇다. 작업 연결 방식 이유 코드 구조 파악·검색 pluck (MCP) 반복 조회, 토큰 절감 브라우저 조작·검사 chrome-devtools (MCP) 세션 상태 유지 시크릿 노출 차단 secret-output-gu...

AI 코딩 에이전트는 .env를 읽는다 — OpenAI도 10개월째 못 막은 문제 AI 코딩 에이전트한테 저장소를 통째로 맡기는 사람이 늘었다. 그런데 그 저장소 안에는 보통 .env 가 같이 들어 있다. 내 경우엔 시크릿이 새는 걸 막는 보안 훅이 오타 하나로 몇 달간 돌지 않고 있었다. 그동안 에이전트가 키 파일을 읽어도 걸러낼 장치가 없었다는 뜻이다. 결론부터 적으면, .gitignore 로는 에이전트한테 시크릿을 숨기지 못한다. 막아야 할 지점은 파일이 아니라 도구 호출이다. 이 글은 그 이유를 OpenAI Codex의 공개 이슈 하나로 짚고, 내 설정에서 .env 가 읽히는지 확인하는 법까지 정리한다. AI 코딩 에이전트 보안에서 가장 자주 새는 구멍이 여기다. 다음 중 하나라도 해당되나 .env 를 .gitignore 에 넣었으니 안전하다고 생각한 적이 있다. 에이전트한테 “이 디렉터리 전체를 분석해줘”라고 시켜 본 적이 있다. API 키나 토큰을 프로젝트 루트의 설정 파일에 그대로 둔 적이 있다. 셋 중 하나라도 해당되면 이 글이 짚는 위험에 노출돼 있다. 왜 그런지는 에이전트가 파일을 읽는 방식을 보면 바로 드러난다. 에이전트가 파일을 읽는 방식 깃과 에이전트는 파일을 보는 길이 다르다. .gitignore 는 git add 단계에서만 작동한다. 깃이 추적하지 않을 파일을 지정할 뿐이다. 반면 코딩 에이전트는 깃을 거치지 않는다. rg (ripgrep)나 grep , cat 같은 도구를 직접 호출해서 파일 시스템을 읽는다. 에이전트 입장에서 .env 는 그냥 텍스트 파일 하나일 뿐이고, 깃이 무시하든 말든 상관이 없다. 그래서 “민감 파일을 .gitignore 에 넣어 뒀으니 에이전트도 안 읽겠지”라는 가정이 깨진다. 에이전트가 코드 검색을 하다가 .env 안의 문자열이 검색어에 걸리면, 그 내용은 도구 출력으로 모델에 전달된다. 모델에 전달된다는 건 외부 서버로 전송된다는 뜻이다. 핵심은 차단 지점이다. 파일에...

하네스(AI 도구를 내 방식대로 굴리는 설정·규칙·자동화 묶음)를 만드는 법은 전에 썼다. 그런데 만든 다음, 그 AI 코딩 설정이 계속 작동하는지는 아무도 점검하지 않는다. 며칠 전 처음으로 내 설정을 전수 점검했다. 몇 달 동안 잘 굴러간다고 믿었던 설정이다. 다 열어보고 든 생각은 하나였다. 절반이 조용히 죽어 있거나, 가짜로 작동하고 있었다. 가장 충격적인 건 보안 훅이었다. API 키가 새는 걸 막으려고 달아둔 훅이, 필드명 오타 하나 때문에 설치된 날부터 한 번도 실행된 적이 없었다. 개발 에이전트 11개는 주석 한 줄 때문에 세션에 등록조차 안 되고 있었다. 설정도 코드처럼 썩는다. 만들고 방치하면 죽은 참조와 작동 안 하는 안전장치가 쌓인다. 영어로는 이걸 설정 부패(config rot)라고 부른다. 누가 읽으면 좋은가 Claude Code·Cursor에 CLAUDE.md·에이전트·훅을 세팅해 본 사람 설정을 한참 전에 만들어두고 그 뒤로 열어본 적 없는 사람 “에러가 안 나니까 잘 돌고 있겠지”라고 믿고 있는 사람 한 줄로 요약하면, 설정 파일에 등록돼 있다는 것과 그 기능이 실제로 작동한다는 것은 전혀 다른 문제였다. 주석 한 줄에 사라진 에이전트 11개 점검에서 가장 먼저 걸린 건 개발 에이전트들이었다. architect, planner, code-reviewer… 정의 파일은 멀쩡히 다 있었다. 그런데 세션에서 단 하나도 호출되지 않고 있었다. 원인은 파일 맨 위에 무심코 넣은 주석 한 줄이었다. # Part of … 같은 한 줄이 그 아래 frontmatter 파싱을 깨뜨렸고, 시스템은 그 파일들을 에이전트로 인식하지 못했다. 정의는 있는데 시스템은 그들을 보지 못한 것이다. 11개가 이 상태였다. 에러도, 경고도 없었다. 그냥 명단에서 빠져 있었다. 한 번도 돌지 않은 보안 훅 더 무서운 건 보안 훅이었다. 시크릿이 화면에 노출되는 걸 막으려고 만든 훅인데, 코드는 tool_result 라는 필드를 보...

프롬프트 엔지니어링 / 에이전트 / 하네스 — 무엇이 다른가 (LLM 워크플로우 용어 지도) Claude한테 일 시키는 방법은 세 가지로 나뉘는 것 같다. 한 마디 잘 묻는 프롬프트 엔지니어링 (Prompt Engineering, 줄여서 PE). 도구를 쥐어준 에이전트 (Agent). 그 위에 운영 틀을 얹은 하네스 (Harness). 셋 다 “AI 활용”으로 묶이지만 무게가 다르다. 어디에 어떤 도구가 맞는지 헷갈렸던 정리를 여기에 적어둔다. 요약 : PE는 한 번의 입력 최적화, 에이전트는 도구를 들고 알아서 도는 AI, 하네스는 그 둘을 어떻게 운영할지 정하는 메타 틀이다. 작은 → 큰 순서로 쌓인다. 5/3 글 에서 다룬 하네스의 내부 구조 는 이 위계 지도의 마지막 칸에 해당한다. 이 글은 Claude Code를 매일 쓰면서 PE·에이전트·하네스라는 단어가 다 비슷해 보였던 사람을 위해 썼다. 입문자가 아니라 한 번씩 다 써본 사람의 정리에 가깝다. 이런 적 있다면 이 글이 도움이 된다 ChatGPT에 비슷한 작업을 시킬 때마다 거의 같은 프롬프트를 매번 다시 입력한 적이 있다. Claude Code가 한 작업에서 5분 만에 토큰 한도를 다 쓴 걸 본 적이 있다. 같은 종류의 실수가 작업마다 또 반복되는 걸 보고 어떻게 멈추지 가 답답했던 적이 있다. 세 가지 모두 같은 원인이다. 셋이 같은 단계가 아니다. 한 번의 입력 최적화로 풀 일, 도구를 쥐어줘야 풀 일, 운영 틀로만 풀 일이 다 섞여 있다. 위계를 잡으면 어디에 시간을 쓸지 가 분명해진다. 한 줄 정의로 시작한다 단계 한 줄 정의 비유 PE (프롬프트 엔지니어링) 한 번의 질문으로 원하는 답을 받아내는 기법 신입에게 일을 한 번 시키는 법 에이전트 도구를 들고 알아서 돌아가는 AI 권한을 받은 1년 차 하네스 에이전트·프롬프트·문맥을 굴리는 운영 틀 회사의 매뉴얼과 평가 체계 자체 작은 단위가 큰 단위에 ...

Codex와 Claude에 같은 명세를 3 condition으로 던졌다 Codex와 Claude에 동일한 Python 함수 명세를 3가지 setup에서 돌렸다. fail-fast 충실도가 약→중→강으로 갈렸고, 그 차이는 모델이 아니라 AGENTS.md 같은 하네스 파일 적용 여부에서 나왔다. 어제 발행한 하네스 엔지니어링 3대 구성요소 글에서 카파시의 이론(컨텍스트 파일·자동 강제 시스템·가비지 컬렉션)을 정리했다. 이 글은 그 이론을 같은 명세 1건으로 직접 측정한 1차 데이터다. YES 3번 — 이런 적 있다면 이 글이 답이 된다 Codex와 Claude Code 차이를 1주 써보고 잘 모르겠다는 결론을 낸 적 있다. 같은 task로 통제 비교를 안 했기 때문에 모델 차이인지 setup 차이인지 분리 못 했다. 도구 비교 글은 많은데 “차이가 어디에서 나오나”를 측정한 글은 본 적 없다. 측정 setup 명세는 Blogger 발행 검증 함수다. verify_published_post(service, blog_id, post_id, expected_title, min_content_length) — 발행 직후 Blogger API로 post를 재조회해 title 일치·content 최소 길이를 검증한다. fail-fast 규칙 적용 (silent default 금지·예외 그대로 raise). 3 condition: Codex v1 — 하네스 0. AGENTS.md 없음. 사용자 시스템 인스트럭션 없음. Claude Opus 4.7 — CLAUDE.md 자동 로드. fail-fast 규칙·Iron Law of Verification 글로벌 메모리에 있음. Codex v2 — Codex v1과 같은 모델. AGENTS.md를 작업 디렉토리에 두고 프롬프트에서 “AGENTS.md 규칙을 적용하라” 명시 인용. 같은 모델·다른 하네스 비교는 1과 3 (Codex v1 vs v2). 다른...