AI 에이전트 개발자라면 반드시 알아야 할 6가지 실전 원칙: 명확한 프롬프트, 컨텍스트 관리, 툴 설계, 평가 루프, 오류 분석, 그리고 시스템적 접근의 중요성을 정리합니다.
가끔씩 이런 질문을 받습니다.
"에이전트 개발이 처음인데, 뭔가 부족한 느낌이에요. 업계에서 통하는 실전 노하우를 좀 알려주세요!"
HuggingFace나 버클리 같은 곳에서 다루는 심화 코스를 추천하고 싶지만, 모두가 그렇게 깊게 들어가고 싶진 않을 겁니다.
그래서 app.build를 개발하면서 크게 도움이 됐던 여섯 가지 실전 경험을 정리해봤습니다. 이 글은 app.build의 설계 결정에서 영감을 받았지만, 초보자도 바로 적용할 수 있게 일반화했습니다.
프롬프트 엔지니어링에 한동안 회의적이었습니다. 엔지니어링이라기보단 샤먼의 제사 의식 같았으니까요. "팁을 100달러 주겠다"거나 "내 할머니가 위독하다", "정확하지 않으면 안 된다"식 프롬프트는 우연히 효과를 볼 수는 있어도 장기적으로 안정적이지 않았습니다.
하지만 내 생각은 바뀌었습니다. 이유는 간단합니다: 최신 대규모 언어모델(LLM)은 꼼수나 감정호소가 아니라, 명확하고 일관된 세부 정보만 필요합니다. 그게 끝입니다. 모델들은 지시를 잘 따르지만, 문제가 되는 건 대부분 지침이 애매모호하기 때문입니다.
모든 LLM 제공자는 자사 모델에 맞는 프롬프트 작성법 가이드를 제공합니다(Anthropic, Google 참고). 그냥 그 가이드대로, 직접적이고 자세하게 쓰면 됩니다. 수작은 필요 없습니다. 예를 들어, ast-grep용 규칙을 Claude에게 생성하게 만든 system prompt 예시도 꼼수 없이 도구 사용법만 담았습니다.
한 가지 팁은, Deep Research 타입 LLM으로 초안 system prompt를 만들고 사람이 보완하는 방식이 기본을 만들기에 매우 좋다는 겁니다.
shared context(공유 컨텍스트) 부분을 유지하는 건 프롬프트 캐싱에도 도움이 됩니다. 시스템 컨텍스트는 크고 정적, 유저 컨텍스트는 작고 동적이면 캐싱 효율이 아주 좋아집니다.
좋은 system prompt를 마련했다면, prompt engineering을 넘어 context engineering으로 발전하는 요즘 추세를 따라야 합니다.
컨텍스트 관리는 언제나 트레이드오프가 있습니다. 적절한 컨텍스트가 없으면 모델이 환각(Hallucination)에 빠지거나, 엉뚱한 대답을 하거나, 너무 긴 컨텍스트 때문에 답 자체를 못 하기도 합니다. 모델의 주의력이 흩어지거나, 비용과 응답 지연도 커집니다.
그래서 저희가 찾은 원칙은, 처음에 꼭 필요한 최소의 지식만 제공한 뒤, 필요할 때 툴로 추가 정보를 가져올 수 있게 설계하라는 것입니다. 예를 들어, 프로젝트 파일 목록만 주고, 변화에 필요한 파일을 읽어들이는 툴을 따로 제공하는 식입니다. 어떤 파일이 반드시 필요하다면 그때만 미리 포함하세요.
로그 같은 피드백 루프 산출물이 컨텍스트를 금방 비울 수도 있으니, 간단한 컨텍스트 압축 도구가 매우 유용합니다. 객체지향의 캡슐화란 말이 흔하지만, 에이전트 컨텍스트 관리에선 더 중요합니다: 각 역할이 꼭 필요한 정보만, 분산해서 관리하세요.
AI 에이전트의 핵심은 툴 호출입니다. LLM + 외부 툴 + 제어 플로우 조합이 곧 에이전트이죠.
에이전트용 툴셋 설계는 API 설계 비슷하지만 사실 더 어렵습니다. 사람은 설명이 부족해도 눈치껏 쓰고, 문서도 알아서 파고, 우회하는 능력이 있지만 에이전트는 그렇지 않습니다(툴이 너무 많으면 컨텍스트 오염!). 단순하고 직관적이며, 허술함이 없도록 하세요. 인간 유저면 비상 상황 처리만 추가해도 괜찮지만, LLM은 예외나 허점을 반드시 남용하기에 허점 없는 설계를 해야 합니다.
잘 만든 툴은 비슷한 수준의 세분화와 엄격한 타입의 소수 파라미터(일반적으로 1~3개, appbuild 예시, opencode 예시)를 가집니다. 초보 개발자에게 줄 API처럼 심플하고 검증된 함수여야 하며, 상태관리 이슈를 막기 위해 멱등성도 추천합니다.
10개 이하 범용 툴(read_file, write_file, edit_file, execute 등) 내에서 설계하고, 필요에 따라 컨텍스트에 따라 추가 툴을 연결하는 것도 좋습니다(예시).
가끔 툴 호출 대신 DSL(도메인 특화 언어)로 실행안을 작성하게 하는 것도 좋은데, 이때도 노출 함수는 잘 설계해야 합니다. 구조만 달라질 뿐, 핵심 원칙은 여전히 "단순하고 충분하며, 명확하고 중복 없는 툴"이 성능의 열쇠라는 점입니다.
뛰어난 에이전트 솔루션은 LLM의 강점과 전통적 소프트웨어의 검증이 결합됩니다. 가장 강력한 방식은 액터-크리틱(Actor-Critic) 구조입니다: 액터(Agent)가 행동을 결정하고, 크리틱(Critic)이 평가하는 구조입니다.
저희 서비스에선 액터는 코드를 새로 만들거나 편집, 크리틱은 테스트, 타입체크, 린트 등 검증을 통해 품질을 평가합니다. 이렇게 미리 정한 도메인 규칙(컴파일 가능, 테스트 통과, 린트 만족 등)을 반드시 체크하는 게 중요합니다. 100% 결정적이진 않지만, 예를 들어 테스트 케이스를 LLM이 생성 후 테스트를 직접 실행하는 식으로도 가능합니다.
어떤 도메인이든, 반드시 도메인 특화 검증(도메인 불변조건 체크)이 필요합니다. ML에서는 이를 귀납적 편향(inductive bias)라 부릅니다.
소프트웨어 분야가 AI 에이전트 영향을 가장 많이 받은 것도 피드백 루프가 명료하기 때문입니다. 컴파일러, 린트, 테스트 등 단순 검증자만으로도 불량 결과를 걸러내기 쉽기 때문입니다. 이는 모델 훈련에도, 후속 제품 개발에도 큰 특혜입니다.
이 마인드는 다른 도메인에도 적용됩니다. 예를 들어, 여행 도우미 에이전트가 다구간 항공권을 제안했다면 실제 연결편 여부를 검증해야 하고, 회계 에이전트라면 복식부기 원칙을 통과하지 못하면 무조건 배제해야 합니다.
피드백 루프는 많은 프레임워크에서 "가드레일"이라는 개념과 연결됩니다. 에이전트는 스스로 회복력을 어느정도 갖지만, 실패 결과를 수정 메시지로 되돌리거나, 더 이상 수정할 수 없다고 판단될 땐 그냥 타임아웃/폐기 후 다시 시도하는 것이 좋습니다.
시스템은 하드/소프트 페일 모두를 가정하고, 다양한 복구 전략을 준비해야 합니다. 이 전략 + 가드레일 = 피드백 루프의 핵심입니다. 이를 몬테카를로 트리 탐색처럼 생각하세요: 유망한 경로만 깊이 탐색하고 나머지는 잘라내는 식입니다.
기본 에이전트에 피드백 루프를 완성하면, 이제 개선과 반복이 시작됩니다. 에러 분석은 AI/ML 엔지니어링의 핵심이고, 에이전트도 예외가 아닙니다.
실패 사례를 하나하나 리뷰할 수도 있지만, 에이전트의 생산성이 너무 좋아서 불가능합니다. 수십 개 인스턴스를 동시에 돌리면 로그가 이미 감당 안 될 정도로 쌓이기 때문입니다. 그래서, 베이스라인-로그 축적-LLM 분석-인사이트 반영이라는 메타-에이전트 루프가 강력합니다.
이렇게 하면 보통, 컨텍스트 관리나 툴 설계의 블라인드 스팟이 아주 잘 드러납니다.
요즘 LLM은 매우 강력해서, 에이전트가 엉뚱한 짓을 하면 바로 실망하게 됩니다. 그런데 사실, 명령 조작(Reward Hacking)에 극도로 민감하게 반응하는 것이 일반적입니다. 즉, 겉으로 드러나는 목표를 최대한 맞추려 하지만, 시스템 설계자가 원하던 목표는 아닐 수 있습니다.
중요한 인사이트: 짜증나는 문제의 원인은 LLM의 한계가 아니라, 필요한 툴 부재, system prompt의 애매함, 컨텍스트 부족 같은 시스템 오류일 수 있습니다.
실제로, "왜 내 에이전트는 명확히 시뮬레이션 데이터 금지시켜놨는데도 연동 툴을 안 쓰고 엉뚱한 답을 내는가?"하고 화를 냈던 적이 있습니다. 로그를 자세히 보니, API 키를 아예 전달 안 해서 데이터 연동이 실행 실패 → 여러 번 실패 반복 → 시뮬레이션 데이터로 대체하는 흐름이었습니다. 파일 쓰기 권한이 없는데도 파일을 쓰려다 실패한 것과 비슷한 케이스도 있습니다.
효과적인 AI 에이전트 제작은 최강 프롬프트나 화려한 프레임워크가 해답이 아닙니다. 시스템 설계와 소프트웨어 엔지니어링 원칙이 본질입니다. 명확한 지시, 적절한 컨텍스트 관리, 견고한 툴 설계, 자동화된 검증 루프가 기반을 이룹니다. 에이전트가 맘에 안 들 때는 모델 탓이 아닌지 먼저 시스템(툴, 프롬프트, 컨텍스트)을 점검하세요.
가장 중요한 것은, 오류 분석을 개발의 1급 시민으로 대우하는 것입니다. LLM의 힘으로 어디서 어떻게 실패하는지 파악하고, 시스템적으로 그 원인을 개선하세요. 완벽한 에이전트가 목표가 아니라, 신뢰할 수 있고, 점진적으로 개선 가능한, 우아하게 장애를 극복하는 에이전트가 목표입니다.
