원문: https://github.com/bang9/how-to-work-with-ai
내가 AI 로 코딩을 할 때 중요하게 여기는 몇가지 요소와 관점들을 글로 적어보았다.
몇가지는 최근에 나온 SKILL 이나 Ralph loop 같은것들과 근원적으로는 궤를 같이 하는데
읽는 분들이 이런 원칙들에 대해 진정으로 이해하게 되기를 바란다.다소 번역체이지만 내용을 이해하는데 문제는 없으니, 대충 읽도록 하자.
AI Agent와 함께 일하는 법
개발 워크플로우에서 AI Agent와 효과적으로 협업하기 위한 실용 가이드입니다.
목차
- 작업이 아닌 도구를 가르치세요
- 진짜 필요한 컨텍스트 문서만 작성하세요
- 모호하게 말하지 말고 명확하게 지시하세요
- 나만의 축약 규칙을 만드세요
- 직접 안 해도 되는 일은 위임하세요
- AI가 스스로 교정할 수 있게 해주세요
- 마지막으로: 인간으로서 해야 할 일
작업이 아닌 도구를 가르치세요
세세한 지시 대신, 올바른 도구를 쥐어주세요.
AI Agent와 일하다 보면 모든 걸 설명하고 직접 처리하게 시키고 싶어집니다. 하지만 AI Agent는 세세한 지시를 받을 때보다 적절한 도구를 쥐어줬을 때 훨씬 잘 동작합니다.
코드 포맷팅을 예로 들어볼게요. 포맷팅 규칙을 AI에게 설명하고 하나하나 고치게 할 수도 있습니다. 하지만 느리고 실수도 많죠. 더 좋은 방법이 있습니다. 이미 설정해둔 포맷터(Prettier나 ESLint 같은)를 실행하는 법만 알려주세요. 명령어 하나면 매번 일관된 결과가 나옵니다.
직접 안 하는 일은 AI한테도 시키지 마세요
좋은 기준이 하나 있습니다. 본인이 손으로 직접 안 하는 일이라면, AI한테도 손으로 하라고 시키지 마세요.
반복 작업은 도구로 만들어두세요. 스크립트를 짜든, 린터를 설정하든, CLI 명령어를 만들든. 그리고 AI에게는 이렇게 알려주세요:
- 실행 방법 — 어떤 명령어를 쓰는지
- 사용 시점 — 언제 이 도구를 쓰면 되는지
- 결과 해석법 — 성공하면 어떻게 보이고, 에러는 무슨 뜻인지
이렇게 하면 AI가 도구를 잘 다루는 숙련된 오퍼레이터가 됩니다. 도구가 이미 잘하는 일을 굳이 흉내내려고 애쓰는 게 아니라요.
진짜 필요한 컨텍스트 문서만 작성하세요
AI가 만든 문서 대부분은 쓰레기입니다. 뭘 남길지 신중하게 고르세요.
AI와 일하다 보면 문서가 쌓이기 쉽습니다. Agent가 문서를 만들고, "나중에 쓸지도 모르니까" 저장하고, 어느새 오래되고 쓸데없이 긴 파일들로 폴더가 가득 차죠. 이러면 득보다 실이 큽니다. 컨텍스트만 늘어나고, 혼란만 생기고, 결국 모든 게 느려집니다.
그럼 뭘 문서로 남겨야 할까요?
모든 걸 기록하지 말고, 반복되는 실수만 기록하세요
패턴을 주목하세요. 기록할 가치가 있는 반복 실수는 두 종류입니다:
-
사람이 놓치는 것들 — 매번 빼먹는 컨텍스트, 무의식적으로 하는 가정, 코드만 봐서는 알 수 없는 프로젝트 특성.
-
AI가 자꾸 틀리는 것들 — AI가 반복적으로 실패하는 구현 패턴, 아키텍처에 대한 오해, 계속 놓치는 엣지 케이스.
이런 패턴이 보이면 그때 기록하세요. 다행히 이런 치명적인 실수들은 생각보다 많지 않습니다. 잘 쓴 가이드 몇 개면 AI가 대부분의 작업을 무난하게 해냅니다.
단순 기록이 아니라 원칙을 남기세요
뭐가 잘못됐는지만 적지 마세요. 이 문제뿐 아니라 비슷한 문제도 해결할 수 있도록 어떻게 접근해야 하는지를 적으세요.
절차가 아니라 원칙을 가르치는 문서를 쓰는 게 목표입니다. 핵심을 잘 추상화하면 가이드 하나로 열 가지 상황에 대응할 수 있습니다. 계속 가치가 쌓이는 문서와 자리만 차지하는 문서의 차이가 여기서 갈립니다.
문서는 필요한 곳에 두세요
문서를 잘게 쪼개서 해당하는 위치에 두세요. CLAUDE.md가 이걸 지원합니다. 특정 디렉토리에 컨텍스트 파일을 두면, AI가 그 영역에서 작업할 때만 불러옵니다.
src/a/ 하위 코드에만 해당하는 가이드라면 거기에 두세요. 그러면 AI가 정말 필요할 때만 해당 컨텍스트를 참조하고, 작업 컨텍스트를 가볍게 유지할 수 있습니다.
모호하게 말하지 말고 명확하게 지시하세요
키워드가 없으면 AI는 헤맵니다.
모호하게 지시하면 AI는 탐색부터 시작합니다. "auth 모듈 수정해"라고 하면 코드베이스에서 "auth module"을 검색하기 시작하죠. 운 좋으면 바로 찾습니다. 아니면 비슷한 키워드로 다시 검색하고, 다른 변형을 시도하고, 이미 알고 있는 걸 찾느라 컨텍스트를 낭비합니다.
구체적으로 지시하세요. 정확한 파일 경로, 클래스 이름, 수정할 함수를 알려주세요. 이런 키워드가 있으면 AI가 추측 없이 바로 찾아 읽고 작업에 들어갈 수 있습니다. 탐색이 줄면 컨텍스트 낭비가 줄고, 속도는 빨라지고, 비용도 줄어듭니다.
애매하면 AI에게 되물으라고 하세요
아무리 명확하게 하려 해도 지시가 모호하게 나올 때가 있습니다. 괜찮습니다. 불명확한 게 있으면 질문하라고 AI에게 미리 말해두세요.
습관을 들이세요. AI가 작업에 들어가기 전에 서로 이해한 게 맞는지 확인하세요. 미리 한 번 맞춰보면 헛수고하는 걸 사전에 방지할 수 있습니다.
큰 그림을 보여주고, 디테일은 AI가 채우게 하세요
방향이 명확하다면 대략적으로 그려주세요. 러프한 인터페이스, 의사 코드, 혹은 머릿속에 있는 구조 정도면 됩니다. 모든 디테일을 다 적을 필요 없습니다.
저는 SDK 개발자로서 주로 인터페이스 정의와 예상 사용법, 동작 방식을 AI에게 알려줍니다. AI가 겉모양을 이해하면 안쪽 구현은 놀라울 정도로 잘 채웁니다. 표면만 제대로 잡아주면 내부는 웬만하면 알아서 잘 구현해줍니다.
나만의 축약 규칙을 만드세요
일관성만 있으면 길게 쓸 필요 없습니다.
모든 걸 풀어서 쓸 필요 없습니다. AI는 패턴을 인식합니다. 규칙을 한번 배우면 그대로 따라옵니다.
예를 들어 UI 스펙을 설명할 때 매번 margin-left: 10px라고 칠 필요 없이 m-left=10이라고 해도 됩니다. 축약 체계를 만드세요. 일관성만 유지하면 AI가 패턴을 파악하고 맞춰서 응답합니다.
컨텍스트도 아끼고, 타이핑도 줄이고, 소통도 간결해집니다. 규칙은 한 번만 정해두고 어디서든 쓰세요. (사실 일관적이고 일반적이면 규칙 자체를 설명하지 않아도 잘 알아듣습니다.)
직접 안 해도 되는 일은 위임하세요
중요해 보이지만 사실 중요하지 않은 일들, 놓아주세요.
코드 포맷팅 같은 건 이미 오래전부터 도구로 자동화해왔습니다. 이제 AI로 더 나아갈 수 있습니다. 커밋 메시지 작성, PR 설명 초안, 보일러플레이트 문서 생성 같은 것들이요.
이런 일들 중 일부는 중요하게 느껴질 수 있습니다. 하지만 솔직히, 매번 직접 신경 쓸 만큼 중요하진 않습니다. 이런 작업들을 찾아서, 직접 하겠다는 생각을 버리고 AI에게 넘기세요. 워크플로우를 세팅하고 Agent가 처리하게 두세요. 그리고 정말 본인이 필요한 일로 넘어가세요.
AI가 스스로 교정할 수 있게 해주세요
AI는 시도하고, 검증하고, 다시 시도할 수 있을 때 잘 동작합니다.
도구를 주는 것과 연결되는 이야기입니다. AI가 작업을 시작하기 전에 결과를 검증할 방법이 있는지 확인하세요. 테스트, 타입 체크, 린터 등 AI가 스스로 자기 작업을 확인할 수 있는 것들이요. AI가 혼자서도 반복할 수 있는 환경을 만들고 알려주세요.
디버깅도 마찬가지입니다. AI가 바로 코드부터 손대게 두지 마세요. 먼저 재현 환경을 만들라고 하세요. 최소한의 테스트 케이스든, 실행 경로와 데이터들을 추적할 콘솔 로그든, 이슈를 확실하게 발생시키는 목 데이터든요. 문제가 재현 가능해진 다음에 수정을 시작해야 합니다. 그리고 기억하세요, 테스트 한 번 통과했다고 고쳐진 게 아닙니다. 특히 타이밍 관련이나 간헐적 이슈는요. AI가 여러 번 검증하게 하세요.
작업이 끝났다고 끝이 아닙니다. 이게 근본적인 수정인지, 아니면 증상만 가리는 임시방편인지 AI에게 평가하게 하세요. 임시방편이면 다시 돌려보내세요. 구현하고, 검증하고, 다듬는 이 사이클이 초기 결과물을 믿을 수 있는 솔루션으로 만들어줍니다.
마지막으로: 인간으로서 해야 할 일
AI는 도구입니다. 그게 만든 결과물에 대한 책임은 본인에게 있습니다.
"새로운 기술에 적응한다"는 핑계로 AI를 엉뚱한 방향으로 계속 밀어붙이지 마세요. AI는 강력하지만 한계가 분명합니다. 시간 낭비 말고 진짜 레버리지를 만드세요. 물론 몇 달 지나면 상황이 완전히 달라질 수 있습니다. AI가 지금 뭘 잘하는지, 어디까지 되는지 계속 파악하면서 사용법을 바꿔가세요. 그리고 일이 편해졌다고 생산성이 올라간 건 아닙니다. 이건 스스로 솔직하게 점검하세요.
AI로 뭘 만들든 본인이 검증할 수 있게 해두세요. 환경을 만들든, 습관을 들이든, 방법은 상관없습니다. AI가 결과물을 만들지만 본인의 지휘 아래 만드는 겁니다. 책임은 본인 몫입니다. 오너십을 가지세요.
그리고 기억하세요. 이제 함께 일하는 파트너가 AI일 수 있지만, 옆자리에 앉아 있는 동료는 여전히 사람입니다. 본인의 책임과 뒤처리를 동료에게 떠넘기지 마세요.
