안녕하세요, Rijul입니다. 저는 모든 커밋마다 실행되는 마이크로 AI 코드 리뷰어인 git-lrc를 만들고 있습니다. GitHub에서 무료로 이용 가능하며 소스 코드가 공개되어 있습니다. 더 많은 개발자가 이 프로젝트를 발견할 수 있도록 git-lrc에 Star를 눌러주세요. 꼭 한번 사용해 보시고 피드백을 공유해 주세요.

AI 에이전트(AI agents)에 대해 읽어보셨다면, AI runbook이라는 용어를 접해 보셨을 것입니다.

또한 사람들이 에이전트가 일상적인 작업을 처리하고, 명령어를 실행하며, 문제를 조사하고, 마치 인간 엔지니어처럼 행동을 수행한다고 자신 있게 말하는 것을 보았을 수도 있습니다.

하지만 여기에는 중요한 차이점이 있습니다:

에이전트가 도구(tools)를 사용할 수 있다고 해서, 무엇을 해야 하는지 또는 어떤 절차(procedure)를 따라야 하는지 알고 있다는 뜻은 아닙니다.

숙련된 엔지니어와 팀에 새로 합류한 신입 사원의 차이를 생각해 보세요.

숙련된 엔지니어는 이미 팀의 표준 절차를 알고 있을 수 있습니다.

신입 사원은 업무를 수행할 기술적 능력은 있을지 모르지만, 여전히 다음 사항들을 배워야 합니다:

• 무엇을 먼저 확인해야 하는지
• 어떤 도구(tools)를 사용해야 하는지
• 어떤 행동을 피해야 하는지
• 팀이 특정 상황을 통상적으로 어떻게 처리하는지

AI 에이전트도 이와 비슷합니다.

에이전트에게 다음과 같이 말했다고 가정해 봅시다:

API가 고장 났어. 고쳐줘.

에이전트는 광범위하게 조사를 시작할 수도 있습니다.

무엇이 실제로 잘못되었는지 파악하기 전에 다양한 파일을 확인하고, 여러 설정을 검사하며, 여러 명령어를 실행하고, 여러 가지 접근 방식을 시도할 수 있습니다.

이는 다음과 같은 결과를 초래할 수 있습니다:

• 시간 낭비
• 토큰(tokens) 낭비
• 불필요한 도구 호출(tool calls)
• 필요 이상의 반복(iterations)

하지만 만약 우리가 이 특정 문제를 처리하기 위한 표준 절차를 이미 가지고 있다면 어떨까요?

에이전트는 그 절차를 따르며 조사를 집중할 수 있을 것입니다.

그것이 바로 AI runbook이 필요한 이유입니다.

AI Runbook이란 무엇인가?

Runbook은 단순히 특정 상황을 처리하기 위해 문서화된 절차입니다.

예를 들어, API가 HTTP 500 에러를 반환하기 시작한다고 가정해 봅시다.

Runbook은 다음과 같이 명시할 수 있습니다:

API가 500 에러를 반환하고 있습니다.

1. API가 실행 중인지 확인하십시오.
...

이는 에이전트에게 따를 수 있는 절차를 제공합니다.

에이전트는 여전히 조사를 수행하고 자신의 도구(tools)를 사용해야 합니다.

런북 (runbook)은 단순히 그러한 조사를 위한 구조를 제공할 뿐입니다.

작은 AI 런북 데모

이를 입증하기 위해, 저는 FastAPI와 SQLite를 사용하여 작은 작업 관리 API를 만들었습니다.

저의 리포지토리를 통해 데모를 직접 시도해 볼 수도 있습니다.

이 프로젝트에는 API 장애를 처리하기 위한 런북이 포함되어 있습니다:

runbooks/
└── api-500-error.md

이제 시나리오를 살펴보겠습니다.

먼저, 서버를 시작합니다.

API가 정상적으로 작동하고 있습니다.

다음으로, 데이터베이스 경로를 다음과 같이 변경하여 의도적으로 애플리케이션을 고장 냅니다:

./data/app.db

에서:

./data1/app.db

로 변경합니다.

이제 헬스 엔드포인트 (health endpoint)를 호출하면, API가 에러를 반환합니다.

이 시점에서, 저는 AI 에이전트에게 문제를 조사하도록 요청합니다.

API가 HTTP 500 에러를 반환하고 있습니다.

runbooks/ 디렉토리에 관련 런북이 있는지 확인하고 그에 따르십시오.
...

애플리케이션 코드를 즉시 수정하는 대신, 에이전트는 런북 (runbook)에 정의된 절차를 따를 수 있습니다:

1. 관련 런북을 찾습니다.
2. API를 확인합니다.
3. 로그를 조사합니다.
4. 데이터베이스 설정을 확인합니다.
5. 잘못된 데이터베이스 경로를 식별합니다.
6. 설정을 수정합니다.
7. API가 다시 정상 상태인지 확인합니다.

에이전트는 여전히 조사를 수행합니다.

런북은 단순히 그 조사에 구조를 부여할 뿐입니다.

이 사례에서 에이전트는 근본 원인 (root cause)을 찾아내고 수정 사항을 적용합니다.

프롬프트 (Prompt) vs 런북 (Runbook)

이 두 가지 지침을 비교해 보십시오.

단순한 프롬프트는 다음과 같이 말할 수 있습니다:

API를 수정하세요.

런북은 더 구체적인 것을 제공합니다:

API가 500 에러를 반환하면, 다음 사항들을 이 순서대로 확인하십시오.

불필요한 변경을 피하십시오.
...

이 차이는 중요합니다.

단순한 프롬프트의 경우, 에이전트는 전체 프로세스를 스스로 파악해야 합니다.

런북이 있으면 에이전트는 **절차적 지식 (procedural knowledge)**을 얻게 됩니다.

에이전트는 다음을 알게 됩니다:

• 무엇을 확인해야 하는지
• 어떤 순서로 확인해야 하는지
• 어떤 조치를 취해야 하는지
• 어떤 조치를 피해야 하는지
• 결과를 어떻게 검증해야 하는지

이는 에이전트의 행동을 더 예측 가능하게 만듭니다.

핵심 아이디어 (The Big Idea)

AI 에이전트는 이미 도구 (tools)를 사용할 수 있는 능력을 갖추고 있습니다.

에이전트는 다음을 할 수 있습니다:

• 파일 읽기
• 명령 실행
• 로그 조사
• 코드 수정
• API 호출

하지만 도구는 오직 **역량 (capabilities)**만을 제공합니다.

런북은 **절차 (procedure)**를 제공합니다.

이것이 AI 런북의 핵심 아이디어입니다.

당신은 단순히 에이전트에게 다음과 같이 말하는 것이 아닙니다:

여기 몇 가지 도구가 있습니다. 알아서 해결해 보세요.

당신은 에이전트에게 다음을 제공하는 것입니다:

이 팀은 보통 이 상황을 다음과 같이 처리합니다. 다음 단계들을 따르되, 필요한 경우 당신의 판단력을 발휘하고, 완료되면 결과를 검증하십시오.

이것이 바로 AI 에이전트에게 절차적 지식 (procedural knowledge)을 제공하는 방법입니다.

그리고 많은 경우, 이는 에이전트에게 모호한 지시를 내리고 최선의 접근 방식을 스스로 찾아내길 바라는 것보다 훨씬 더 예측 가능한 결과로 이어질 수 있습니다.

AI 런북 (AI runbooks)에 대한 이 소개는 여기까지입니다.

AI 에이전트는 코드를 빠르게 작성합니다. 하지만 당신에게 알리지도 않고 조용히 로직을 제거하거나, 동작을 변경하고, 버그를 유발하기도 합니다. 이러한 사실은 종종 운영 환경 (production)에 도달해서야 알게 됩니다.

git-lrc가 이를 해결합니다. 이 도구는 git 커밋 (git commit)에 연결되어 모든 차이점 (diff)이 반영되기 전에 검토합니다. 설정에는 60초가 소요되며, 완전히 무료입니다.

모든 피드백과 기여자를 환영합니다! 온라인에서 소스 확인이 가능하며(source-available), 누구나 사용할 준비가 되어 있습니다.

Github에서 ⭐ star를 눌러주세요