AI와 매일 개발하며 정착된, 소소하지만 효과적인 노하우 정리

평소 개발할 때는 Claude Code를 메인으로, Codex CLI나 Cursor 등을 병용하며 매일 사용하고 있습니다.

매일 사용하다 보니, "이렇게 하면 출력이 안정된다", "이 부분은 주의하지 않으면 사고가 난다", "이것은 습관으로 만들어 두길 잘했다"라는 것들이 조금씩 쌓여왔습니다. 이 기사는 그것들을 한 번 정리해 본 내용입니다.

특별한 것을 하고 있지는 않습니다. 공식에서 제공하는 기능을 솔직하게 사용하는 것과 약간의 운용상의 노하우를 쌓아온 것이 대부분입니다. 무언가 도움이 될 만한 것이 있다면 하는 마음으로 정리하겠습니다.

정리해 보니, 제가 하고 있는 일은 결국 "AI와의 인식 차이를 줄이기", "매번 반복되는 일을 시스템(Mechanism)으로 넘기기", "문맥(Context)을 도구 외부에 남기기" 이 세 가지로 집약되어 있었습니다. 기사도 전반부에서는 평소 작업 방식을 흐름에 따라, 후반부에서는 이를 뒷받받하는 환경 구축과 아직 시행착오 중인 노하우를 순서대로 작성하겠습니다.

이 부분은 요구사항 → 설계 → 구현 → 세션 구분이라는 평소의 흐름에 따라 나열했습니다. 관통하는 핵심은 "코드를 쓰기 전에 AI와의 차이를 없애고, 쓴 후에는 다음 작업을 이어가기 쉬운 형태로 끊어둔다"는 의식입니다.

이것은 새로운 이야기는 아니지만, 다시 한번 의식하게 된 부분이 바로 이것이었습니다.

평소 업무에서 "이런 기능을 만들어줘"라고 대략적으로 의뢰받았을 때, 아마 동작하는 것은 만들어낼 수 있겠지만 의뢰한 사람이 머릿속으로 그렸던 것과는 조금 다른 결과물이 나오는 경우가 있습니다. 서로의 인식이 어긋나 있어서 구현 도중에 그것이 드러나는 흐름이 되기 쉽습니다.

AI도 완전히 똑같다고 생각합니다. "이거 할 수 있어?"라고 물으면 "할 수 있습니다"라고 답하며 코드도 작성합니다. 동작도 합니다. 하지만 내가 생각했던 완성형과는 미묘하게 어긋나 있는 경우가 자주 발생합니다.

이것은 AI가 잘못된 것이 아니라, 이쪽에서 전달한 정보의 범위 내에서 AI가 충실하게 만들어주고 있을 뿐입니다. 차이를 줄이고 싶다면 이쪽에서 정보를 늘릴 수밖에 없다는 이야기였습니다.

특히 구현 단계(Implementation Phase)에서는 "얼마나 많은 정보를 전달할 것인가"를 의식하도록 하고 있습니다. 구체적으로는,

• 기대하는 입출력이나 간단한 테스트 케이스 ("X를 전달하면 Y를 반환한다")
• "기존의 〇〇 파일과 같은 구조로"와 같은 참고 패턴
• "이 파일만", "이 기능의 범위만"과 같은 스코프(Scope) 설정
• 버그 수정이라면 증상, 재현 절차, "고쳐졌다"라고 말할 수 있는 조건

사람의 경우에는 요구사항이나 사양을 적거나 모르는 것을 사전에 확인하는 일을 자연스럽게 수행하지만, AI를 상대로 하면 "금방 써줄 것 같으니까"라며 생략하고 싶어집니다. 생략한 만큼 나중에 다시 작업하게 됩니다. 이 부분이 아마 출력의 질에 가장 큰 영향을 미치는 포인트라고 생각합니다.

정보를 전달하는 방식과 세트로 습관화하고 있는 것이 플랜 모드(Plan Mode)를 사용하는 것입니다.

구현을 갑자기 시작하게 하지 않고, 먼저 "어떻게 만들 생각인지"를 내놓게 한 뒤 스스로 리뷰합니다. 여기서 인식의 차이를 깨달을 수 있다면 코드를 쓰기 전에 수정할 수 있습니다. 코드를 다 작성한 후에야 방침이 다르다는 것을 알게 되면 통째로 다시 해야 하므로, 그 직전에 멈춰 세우는 감각입니다.

특히 3단계 이상으로 나뉘는 것 같은 태스크는 거의 플랜 모드부터 시작합니다. 플랜을 보고 "아, 여기 의도와 다르네"를 아는 것만으로도 충분히 본전을 뽑는 것이며, 결과적으로 이것이 재작업을 가장 많이 줄여주고 있다고 느낍니다.

최근에는 여기에 더해, 플랜을 "질문 공세"로 만들어달라고 요청하기도 합니다. grill-me / grill-with-docs라는 스킬을 사용하고 있는데, 이는 Matt Pocock 씨가 공개한 스킬 모음집에 포함되어 있는 것입니다.

대략 말하자면, 플랜 모드가 "AI가 안을 제시함 → 내가 리뷰함"이라면, grill 계열은 그 반대 방향입니다. AI가 설계 트리를 하나씩 따라가며, 아직 결정되지 않은 부분이나 모호한 부분을 하나씩 질문해 옵니다. 대답하는 과정에서 "아, 여기는 나도 확실히 결정하지 못했었구나"라는 점이 드러나는 것이 재미있는 부분입니다.

: 대화 전용. 플랜이나 설계를 끊임없이 질문받으며 인식을 맞추는 grill-me

: 마찬가지로 질문을 받으면서, 확정된 용어나 결정 사항을 그 자리에서 CONTEXT.md (용어집)나 ADR에 기록해 주는 grill-with-docs. 나중에 "그 용어가 어느 쪽 의미였더라" 하는 일이 없어짐.

플랜 모드(Plan mode)가 코드를 작성하기 전의 오차를 줄이는 과정이라면, grill 계열은 그보다 앞서 "애초에 내 머릿속이 정리되어 있는가"에 대한 오차를 줄이는 과정입니다. 질문을 받지 않으면 자신이 모호하게 남겨두었던 부분을 깨닫지 못하기 때문에, 이 부분을 언어화하게 만드는 것만으로도 설계의 정밀도가 올라가는 느낌을 받습니다.

설계를 다듬는 시간은 에이전트(Agent)를 늘리지 않고 Claude Code와 1 대 1로 대화하도록 하고 있습니다. 사고의 일관성이 깨지는 데 따르는 디메리트가 더 크기 때문에, 여기서는 의도적으로 1 대 1을 유지한다는 방식의 구분입니다 (grill 계열도 이 1 대 1 대화와 궁합이 좋습니다). 재작업이 줄어드는 만큼 불필요한 토큰 소비도 억제할 수 있어, 이용 한도 내에서 작업을 오래 지속할 수 있다는 점도 소소한 장점입니다.

설계가 확정된 후의 구현 단계는 병렬화합니다. 설계가 결정되어 있으면 작업을 분담할 수 있으므로, 이때 비로소 멀티 에이전트(Multi-agent)가 효과를 발휘합니다.

방법은 간단합니다. 확정된 설계를 바탕으로 독립적으로 진행할 수 있는 작업을 여러 개의 서브 에이전트(Sub-agent)에게 할당하여 동시에 실행하는 형태입니다. 같은 파일을 동시에 건드리면 덮어쓰기 사고가 발생할 수 있으므로, 영향 범위가 클 때는 git의 worktree를 사용하여 작업 트리 자체를 분리하고 별도의 디렉토리에서 실행합니다. 무거운 탐색이나 시행착오도 서브 에이전트에게 넘겨버리면, 메인 대화의 컨텍스트(Context)가 오염되지 않는다는 점도 이점입니다.

또 하나 습관으로 삼고 있는 것은 여러 AI를 병용하는 것입니다. Claude Code를 메인으로 사용하면서, Codex CLI에는 설계 검토나 코드 리뷰를 맡깁니다. 같은 태스크를 양쪽에 던져 경쟁시키는 것이 아니라, Claude Code가 구성한 설계나 작성한 코드를 Codex에게 읽게 하여 위화감을 찾아내도록 하는 분업에 가깝습니다.

구현과 같은 모델에게 리뷰를 맡기면 동일한 사고의 습관을 놓치기 때문에, 다른 모델에게 맡기는 것이 지적의 질을 높인다는 것이 현재까지의 체감입니다. 사람도 자신이 작성한 코드보다 타인의 코드를 리뷰할 때 결함이 더 잘 보이는 것과 같다고 생각합니다.

도구를 넘나들다 보면 "방금 저쪽에서 무슨 이야기를 했었는지" 알 수 없게 되기 쉬우므로, 각 도구의 대화 요점을 한 곳에 정리해 두면 인수인계가 쉬워집니다.

긴 세션을 진행하다 보면 컨텍스트가 비대해져 동작이 불안정해집니다. 이때 사용하는 것이 /compact와 /clear입니다.

: 같은 작업을 계속하고 싶지만 컨텍스트가 무거울 때. 요약만 남기고 계속 진행하는 /compact

: 작업 테마가 바뀔 때. 이전 문맥을 끌고 오면 역효과가 나므로 일단 전부 버리는 /clear

타이밍의 기준은 "여기서 일단 점심시간을 갖고, 돌아와서 이어서 하고 싶다"라고 생각되는 순간입니다. 같은 작업을 계속하고 싶다면 /compact, 다른 태스크로 전환한다면 /clear로 구분합니다.

어느 경우든 "과정"은 사라져도 좋지만 "결론"은 별도의 파일에 남겨두도록 하고 있습니다. 설계 플랜이나 그날의 작업 로그를 Markdown으로 작성해 두면, 오늘 안에 끝나지 않더라도 다음 날 그 파일을 다시 읽는 것만으로 이어서 할 수 있습니다. "어제 어디까지 했더라"를 기억에 의존하지 않아도 된다는 점이 소소하게 큽니다. /clear는 처음에는 버리는 것이 두려웠지만, 결론만 남겨두고 있다면 과감하게 사용할 수 있습니다.

여기서부터는 자주 사용하는 지시나 절차를 커맨드(Command), 스킬(Skill), Hook 등으로 정리하여, Claude Code를 자신의 작업에 맞춰 구성해 나가는 이야기입니다.

매일 사용하면서 소소하게 가장 효과를 보고 있는 것이 아마 이것일 것입니다.

Claude Code와 Codex에는 Skill / Slash Command / Hook / Subagent / MCP와 같은 확장 포인트가 마련되어 있습니다 (도구에 따라 이름이나 갖춰진 범위는 조금씩 다릅니다). 처음에는 이름만 아는 상태로 막연하게 사용해 왔지만, 이제는 하나씩 문서를 읽고 실제로 만져보는 시간을 의식적으로 갖기로 했습니다. 거창한 독자 커맨드를 만들어내는 이야기가 아니라, 우선 공식 기능을 한 번씩 파악하고 그대로 사용하는 것뿐입니다.

대략적인 개인적 이해는 다음과 같습니다.

Skill: "이 상황일 때만 읽어주었으면 하는 전제"를 분리하는 곳. CLAUDE.md (Codex라면 AGENTS.md

）와 같이 항상 읽어들이는 파일에 전부 적으면 무거워지므로, 기능별로 나누어 둡니다 (앞부분에서 사용한 grill도 이 Skill 중 하나입니다).

• Slash Command: 매번 똑같은 전제를 입력하고 있다고 느껴지면, 그것을 명령어로 묶어버립니다.
• Hook: 특정 조작의 전후에 처리를 끼워 넣는 메커니즘. "해서는 안 될 조작을 자동으로 차단하기", "수정 후에 자동으로 lint 실행하기"와 같이, 사람이 매번 주의를 기울이지 않아도 되도록 만드는 용도입니다.
• Subagent: 메인 대화에 넣고 싶지 않은 작업(대량의 파일을 읽는 탐색, 리뷰만 시키기 등)을 별도의 컨텍스트(Context)로 분리하는 용도입니다. 직접 정의를 만들지 않아도 내장된 서브 에이전트(Subagent)가 기본적으로 동작하므로, 구현 단계의 병렬화는 우선 이것만으로도 충분합니다. 직접 만드는 것은 사용 가능한 도구를 제한하고 싶을 때, 전용 역할이나 시스템 프롬프트(System Prompt)를 부여하고 싶을 때, 모델을 고정하고 싶을 때, 혹은 특정 작업에서 자동으로 호출하게 하고 싶을 때와 같이 어떠한 커스텀이 필요해졌을 때만 하면 됩니다.
• MCP: AI를 외부 데이터나 도구에 연결하는 메커니즘. 라이브러리의 공식 문서 취득이나 코드의 심볼(Symbol) 단위 검색과 같은 "읽기" 계열뿐만 아니라, Notion·브라우저 조작(Playwright)처럼 외부 서비스를 "조작"하는 계열까지 맡길 수 있습니다. 답변의 근거가 실제 데이터와 연결되어 거짓 정보가 줄어들고, AI의 작업 범위가 에디터 외부까지 확장되는 점이 효과적입니다.

그중에서도 Hook은 최근 자주 사용하게 되었습니다. 사용법은 크게 두 가지로, "매번 해주었으면 하는 일을 자동으로 끼워 넣는 것"과 "해서는 안 되는 일을 막는 것"입니다. 전자는 예를 들어 "코드를 수정하면 lint나 테스트를 자동으로 실행한다"와 같습니다. 매번 "수정하면 테스트 돌려줘"라고 말로 부탁할 수도 있지만, 이 역시 말하는 것을 잊어버릴 수도 있고 AI 측에서도 잊어버릴 수 있습니다. Hook으로 설정해 두면 편집이 들어갈 때마다 알아서 실행되므로, 아무도 기억하지 못해도 매번 확실하게 실행됩니다. 후자는 건드리고 싶지 않은 조작이나 금지하고 싶은 명령어를 차단해 두는 사용법으로, AI가 실수로 실행하려고 해도 막을 수 있습니다. 두 가지 모두 공통점은, "매번 부탁하기·매번 주의하기"를 시스템(Mechanism)으로 바꿀 수 있다는 것입니다. 인간의 주의력에 의존하지 않아도 된다는 점이 Hook의 장점이라고 생각합니다.

확장 포인트를 단순히 "사용"하는 것을 넘어, "애초에 무엇을 확장 포인트로 삼아야 하는가" 자체를 AI가 찾아내게 할 수 없을까 하여 최근 시도하고 있는 것이 이것입니다.

매일 AI와 작업하다 보면,

• 매번 똑같은 말을 하고 있다 (똑같은 전제, 똑같은 주의 사항)
• 매번 똑같은 명령어를 금지하고 있다
• 매번 똑같은 명령어를 실행하고 있다

와 같은 "반복"이 반드시 나타납니다. 이것은 본래 Skill이나 Hook, 명령어로 묶어버리면 매번 말할 필요가 없는 것들입니다. 하지만 작업에 집중하다 보면 "아, 이걸 반복하고 있구나"라고 깨닫는 것 자체가 어렵습니다.

그래서, 1주일 정도의 단위로 AI 자신의 메모리나 대화 이력(History)을 AI가 스스로 되돌아보게 하여, "이것은 Skill로 만들면 어떨까?", "이것은 Hook으로 자동화하면 어떨까?"라고 제안받는 방식을 조심스럽게 시도하고 있습니다.

• 매번 수동으로 말하는 전제 → Skill로 만들 후보
• 매번 금지하고 있는 명령어 → Hook으로 차단할 후보
• 매번 실행하고 있는 명령어 → 명령어화·자동화할 후보

인간은 "최근에 무엇을 자주 반복했는지" 떠올리는 데 서툴지만, 이력이라는 기록이 남아 있다면 거기서 찾아내는 것은 AI가 잘하는 작업입니다. 자신의 작업 습관을 AI가 정리(Inventory)하게 하여, 번거로운 부분을 시스템으로 바꾸어 나가는 이미지입니다.

아직 체계로 굳어진 것은 아니지만, "반복을 깨닫는 것"을 인간의 기억력에 의존하지 않는 형태로 만들 수 있을 것 같다는 예감이 듭니다.

세션을 넘나들어도, 도구를 넘나들어도 사라지지 않는 "결론의 보관 장소"를 어디로 할 것인가. 앞서 말한 /clear로 결론을 별도 파일에 남기는 이야기나, 도구 간의 인수인계 이야기와 이어지는 부분입니다. 최근에는 설계 문서나 작업 로그, 프로젝트별 지식을 Obsidian에 정리하고 있습니다.

Obsidian은 Markdown 형식으로 메모를 작성할 수 있는 앱입니다. 데이터는 기본적으로 자신의 PC에 로컬로 저장되며, 링크로 연결하여 "지식의 네트워크"를 만들어 나갈 수 있는 것이 특징입니다. 내용은 단순한 Markdown 파일이므로 AI에게 전달하기에도 궁합이 좋습니다.

이것이 효과적인 이유는, Obsidian 측에서 미리 AI에게 전달할 전제 조건을 정리해 둘 수 있기 때문입니다. 프로젝트의 전제 조건이나 결정 사항을 깔끔하게 작성해 두면, Claude Code에도 Codex에도 동일한 전제를 공유할 수 있습니다. 도구를 넘나들더라도 "말한 것과 말하지 않은 것" 사이의 어긋남이 생기기 어렵습니다. AI의 메모리 기능이나 대화 기록은 해당 도구 안에 갇혀 있지만, Obsidian에 꺼내 놓으면 도구 외부의 "외부 기억 (External Memory)"으로서 어떤 AI로부터도 참조할 수 있는 상태가 됩니다.

직접 쓰면서 정리해 보니, 최근에 방식을 바꾼 부분은 이 정도였습니다.

평소 진행 방식에서 바꾼 것:

• AI에게도 사람에게 의뢰할 때와 마찬가지로 충분한 정보를 전달한다 (특히 구현 (Implementation) 단계)
• 설계는 플랜 모드 (Plan mode)와 grill을 사용하여, 코드를 작성하기 전에 차이를 없앤다
• 구현은 멀티 에이전트 (Multi-agent) + 복수 AI를 활용하여 병렬화한다. 리뷰는 별도의 모델 (Codex)에 맡긴다
• /compact와 /clear를 타이밍에 맞춰 구분하여 사용하고, 결론은 별도의 파일에 남긴다

환경 구축에서 바꾸거나 시도하고 있는 것:

• Skill / Command / Hook / Subagent / MCP라는 공식 확장 포인트를 조사하여 그대로 사용한다
• 이력으로부터 스킬화(Skill) 또는 훅화(Hook)할 소재를 AI 스스로 제안하게 한다 (시행착오 중)
• Obsidian을 AI의 "외부 기억 (External Memory)"으로 만든다 (시행착오 중)

화려한 기술을 쓰는 것은 아니며, 모두 "작은 궁리" 수준입니다. 서두에도 썼듯이, 결국은 **"차이를 줄인다", "반복을 시스템으로 넘긴다", "문맥을 외부에 남긴다"**라는 세 가지를 다양한 상황에서 반복하고 있을 뿐이라고도 할 수 있습니다. 다만, 매일 만지는 도구이기 때문에 이러한 작은 궁리들의 축적이 꽤 큰 효과를 발휘합니다.

한 가지 더, 테크닉이라기보다 마음가짐에 대한 이야기를 덧붙이자면. AI를 중심으로 작업하게 된 이후로 자연스럽게 PC 안의 파일을 정리하게 되었습니다. AI가 망설임 없이 움직이게 하려면, 어디에 무엇이 있는지가 명확해야 하기 때문입니다. 이는 인간이 무언가를 찾을 때와 마찬가지여서, AI를 위해 정리한다고 생각한 것이 결과적으로 자신의 머릿속까지 정리해 줍니다. 이 "정리하는 습관"이 생긴 것이, 수수하지만 가장 큰 변화였을지도 모릅니다.

이야기가 길어졌습니다만, 이 중 하나라도 내일의 작업부터 시도해 볼 수 있는 것이 있다면 기쁘겠습니다.