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

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

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

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

하네스 엔지니어링 — CLAUDE.md만 쓴다고 끝나지 않는다 (3대 구성요소) CLAUDE.md를 썼는데도 Claude가 같은 실수를 반복한다면, 그건 CLAUDE.md가 부족해서가 아니다. 하네스 엔지니어링 이 부족해서다. CLAUDE.md는 하네스의 한 구성요소일 뿐이다. 안드레 카파시(전 OpenAI 창립 멤버, 전 Tesla AI 책임자)가 17분짜리 영상 에서 정의한 이 개념의 핵심은 한 줄로 압축된다. “모델이 아닌 모든 것이 하네스다.” 요약 : CLAUDE.md만으로는 Claude가 같은 실수를 반복한다. 하네스 엔지니어링은 컨텍스트 파일, 자동 강제 시스템, 가비지 컬렉션 3가지로 이뤄진다. 이 글은 카파시 프레임의 한국어 정리에 더해, 1인 운영자가 실제로 어떻게 굴리고 있는지 메커니즘 한두 개씩 보여준다. CLAUDE.md “어떻게 쓰나”는 이전 글 에서 다뤘다. 이 글은 Claude Code를 매일 쓰면서 같은 실수를 반복하는 사람을 위해 썼다. 입문자라면 이전 글이 먼저다. 이런 적 있다면 이 글이 도움이 된다 CLAUDE.md에 “console.log 금지”라고 썼는데 며칠 뒤 또 console.log가 박힌 코드를 받은 적이 있다. pre-commit이 없어서 타입 에러 그대로 push된 코드를 배포한 적이 있다. 에이전트가 만든 임시 함수와 미사용 import가 6개월째 쌓여 있는 코드를 본 적이 있다. 세 가지 모두 같은 원인이다. 부탁만 했고, 강제하지 않았다. 카파시는 영상에서 한 줄로 정리했다. “프롬프트 = 부탁, 하네스 = 강제.” 1. 컨텍스트 파일 — CLAUDE.md CLAUDE.md는 매 세션 시작에 Claude가 항상 읽는 기준 문서다. 작성법은 별도 글에서 다뤘으니, 여기서는 운영 메커니즘 하나만 보여준다. 위치 적용 범위 용도 ~/.claude/CLAUDE.md 모든 프...