AI가 모든 것을 알아서 해결해 줄 것 같지만, 실무에서는 기대와 다른 결과가 자주 나옵니다. 실제 프로젝트에서 AI를 활용하여 코딩을 하면서 맥락을 제대로 이해 못하거나 다른 방향으로 코딩을 하는 경우를 겪였습니다. AI 자체의 성능도 중요하지만 성능보다, AI가 맥락을 잘 이해하고 일하도록 만드는 운영 시스템이 더 중요했습니다.
이번 글에서는 제가 효과를 본 4가지 전략을 정리합니다.
AI활용한 코딩이 자주 빗나가는 이유
요즘은 codex, Claude code, Gemini ClI 등 다양한 도구를 활용하여 개발 하고 있지만 아래와 같은 문제가 반복됩니다.
- 맥락 유지 한계 작업 초반에는 지시를 잘 따르다가도, 대화가 길어지면 핵심 맥락을 놓치는 경우가 있습니다.
- 지침 참조 누락 가이드 문서를 제공해도 AI가 능동적으로 찾아보지 않아, 팀 규칙, 코드 규칙이 반영되지 않는 경우가 생깁니다.
- 완료 보고와 실제 개발 코드 품질의 차이 "완료했습니다", "지시사항 모두 반영하여 작업 했습니다",라는 답변이 나왔지만, 검토해 보면 오류나 누락이 남아 있는 경우가 많이 발생합니다.
이 세 가지가 쌓이면 생산성이 오르지 않고, 오히려 검수 비용이 증가하는 상황이 발생합니다.
AI를 활용하여 코딩을 할 때
새로운 기능 및 기능 수정 보완 작업을 진행을 AI를 통해 작업을 했습니다. 결과 적으로 빠른 시간안에 개발을 진행할 수 있었습니다.
AI와 협업하면서 코딩 시 "AI를 잘 쓰는 법"이 아니라 "AI가 잘 일하게 만드는 구조"가 중요 했습니다. 같은 팀개발자에게 매뉴얼과 체크리스트, 개발 가이드, 기획 등등 문서를 제공하듯, AI에게도 동일한 운영환경을 제공하여 작업을 진행할 수 있도록 해야 했습니다.
전략 1. 자동 매뉴얼 시스템: 지침을 스스로 참조하게 만들기
AI는 지침을 전달받아도 매번 충실히 활용하지는 않습니다. 그래서 저는 지침을 "읽으라고 요청하는 방식"에서 "자동으로 연결되는 방식"으로 바꿨습니다. (skills 활용)
적용 방식
- 작업 시작 전 프롬프트에 입력 된 키워드를 활용하여 skill 지침을 우선 참조 하게 합니다.
- 작업 종료 후 완료 응답 직후 결과물을 확인하고, 누락되기 쉬운 항목을 체크리스트로 만들어서 재확인 시킵니다. 예: 오류 처리, 보안 점검, 예외 케이스 반영 여부.
문서 구조 최적화
처음에는 rules을 만들어서 하나의 대형 문서로 운영했는데 비효율적이었습니다. 많은 토큰을 소비하고 필요 없는 내용에 대한 지침도 읽었습니다. 그래서 skills를 활용해 description만 보고도 AI가 스스로 참조하는 문서인지를 인지 시켰습니다. 프로젝트 기준으로는 토큰 사용량이 크게 줄었고, 불필요한 프롬프트 내용도 감소했습니다.
전략 2. 작업 기억 시스템: 계획을 외부 문서로 고정하기
AI 협업에서 가장 큰 리스크는 긴 작업에서 맥락을 잃어 버리는 순간입니다. 이를 막기 위해 작업 시작 시점마다 아래 3개 문서를 먼저 만듭니다.
- 계획 문서 (plan 모드) 목표와 구현 흐름을 처음부터 끝까지 정리한 문서
- 맥락 기록 왜 그런 결정을 했는지, 관련 근거가 어디 있는지 남기는 문서
- 진행 체크리스트 완료/미완료 작업을 추적하는 문서
운영 절차
- 먼저 AI한테 내 지시사항에 따른 실행 계획을 작성한다.
- 사람이 계획을 검토하고 수정한다.
- 승인된 계획을 3개 문서에 저장한 뒤 구현을 시작한다. (각각 문서를 에이전트 별로 작업을 시킨다.)
핵심은 "계획 승인 후 바로 구현"이 아니라 "문서화 후 구현"입니다. 이 단계를 지키면 대화가 길어져도 작업 축이 유지되고, 재시작 비용이 크게 줄어듭니다.
새로운 기능이나 추가기능이 발생하거나 해당 기술을 반복적으로 사용해야한다면 skill로 만들어서 재활용이 가능하도록 문서화 합니다.
전략 3. 자동 품질 검증: 계획에 대한 구현 완료 시점에 강하게 검사하기
작업 중간의 결과는 완성 되지 않아서 검증하기에는 좋지 않습니다. 그래서 중간중간 과도하게 검사시키는 것 보다는, "게획에 대한 구현 완료 시점"에 검증을 시킨 후 추가 작업이 필요한 리스트를 작성하여 새로운 계획을 세워서 작업하는 방식을 사용합니다.
전략 4. 전문 AI 대리인: 역할 분리로 품질 높이기
하나의 AI에게 모든 역할을 맡기면 편하지만, 품질 편차가 커집니다. 그래서 팀처럼 역할별 에이전트를 만들어서 작업을 진행 시킵니다.
- 구현 담당
- 테스트 담당
- 코드 리뷰 담당
- 품질 점검 담당
특히 리뷰 담당 에이전트에게는 아래 보고 형식을 고정했습니다. "무엇을 발견했는지, 무엇을 수정했는지, 왜 그렇게 판단했는지"를 문서로 남기게 하면, 수정 근거가 명확해지고 반복 오류도 줄어듭니다.
정리
AI 생산성을 끌어올린 핵심은 AI도구 교체가 여러 도구별로 잘하는 일을 시키고, AI가 맥락을 잘 이해하고, AI가 일을 잘하는 운영 시스템이 중요 했습니다. 프로젝트에서 실제로 효과를 본 원칙은 다음 4가지입니다.
- 프로젝트 서비스 별로 skill 지침 참조를 자동화한다.
- 구현 plan을 AI에게 작성 시키고 문서화 하여 기억을 외부화한다.
- 완료 시점 검증을 통해 구현에 대한 리뷰 및 품질을 향상 시킨다.
- 한명의 AI한테 모든일을 시키는 것 보다는 전문 에이전트로 역할을 만들어서 검토 및 작업을 진행 시킨다.
AI는 단독으로는 그냥 일을 시키면 뒤로 갈 수록 점점 작업에 대한 지시가 흔들릴 수 있지만, AI가 일을 잘할 수 있도록 시스템을 만들어주면 안정적으로 구현 및 개발을 진행합니다. 특정 AI도구를 쓰는지보다, 어떤 관리 구조를 갖췄는지가 결과를 더 크게 좌우하는 것 같습니다. AI도구는 도구일 뿐, AI가 일을 잘하도록 만드는 시스템이 더 중요하다고 생각합니다.
다음 글에서는 skills을 어떻게 만들고, 마켓에 등록되어있는 추천 skills에 대하여 소개하겠습니다.