경험을 저장소에 기록하기

최근 OpenAI의 Skills와 Agents SDK를 다룬 글을 읽으며 머릿속에서 계속 맴돌던 아주 작은 질문이 있습니다.

우리가 AI를 사용하는 것일까, 아니면 자신의 업무 방식을 조금씩 정리해 AI도 이해하고 활용할 수 있는 형태로 만드는 것일까.

예전에는 ‘AI를 통한 효율화’의 핵심이 모델의 성능이 계속 좋아지는 데 있다고 느꼈습니다. 모델은 코드를 작성하고, 오류를 설명하고, 문서를 요약하며, 모호한 요구사항을 어느 정도 쓸 만한 구현으로 바꿔 주기도 합니다. 하지만 이런 AI를 실제 개발 업무에 넣어 보면, 이내 문제가 구체적인 수준으로 내려옵니다.

그런데 문제를 파헤쳐 보면, AI가 충분히 똑똑하지 않아서가 아니라, 여러분이 평소 일을 어떤 방식으로 하는지 AI가 알지 못한다는 사실이 자주 드러납니다.

코드 수정을 마친 뒤의 ‘한 번 확인해 줘’도 마찬가지입니다. 어떤 사람은 format, lint, test를 모두 돌리고, 다른 사람은 현재 모듈만 실행하며, 또 다른 사람은 typecheck까지 챙기고, 어떤 이는 CI가 알아서 처리해 줄 것이라고 기본값으로 둡니다.
PR을 준비할 때도 마찬가지입니다. 누군가는 변경 배경, 영향 범위, 검증 방식을 매우 분명하게 적지만, 누군가는 짧은 제목만 남기고 리뷰어가 나머지를 전부 파악하도록 맡깁니다. 마치 강에 돌을 던진 뒤 생기는 물결을 리뷰어가 알아서 헤아리게 두는 것 같습니다.

이런 차이는 개인의 습관처럼 보입니다. 하지만 한 층 더 생각해 보면, 이건 사실 공식적으로 기록되지 않은 경험입니다.

Skills가 흥미로운 점은 바로 여기에 있습니다.

Skills는 모델이 조금 더 많은 것을 알게 만드는 것도 아니고, prompt를 더 세련된 이름으로 다시 부르는 것도 아닙니다. 오히려 다음과 같이 말하는 것에 가깝습니다. 어떤 일이 반복해서 발생하고, 그 일에 이미 비교적 안정적인 방식이 있다면, 왜 이를 진지하게 적어서 저장소에 담고, 호출할 수 있는 능력으로 만들지 않을까요?

이 아이디어는 저를 조금 움직였습니다. 더 화려한 지능을 추구하는 것이 아니라, 오히려 아주 소박한 일을 하고 있기 때문입니다. 원래 사람 머릿속에만 있던 업무 습관을 조금씩 시스템의 일부로 정리해 나가는 것이지요.

Skill은 무엇과 닮았을까

표면만 보면 skill은 ‘프롬프트 템플릿’으로 이해하기 쉽습니다.

하지만 점점 더 skill은 훨씬 작은 업무 단위처럼 느껴집니다.
자신이 언제 나타나야 하는지, 무엇을 해야 하는지, 어떤 부분은 모델의 판단에 맡기고 어떤 부분은 스크립트가 실행해야 하는지 알고 있습니다.

OpenAI의 글에서 skill은 일반적으로 자체 설명 파일을 갖고, 스크립트, 참고 자료, 심지어 보조 리소트까지 함께 포함할 수도 있다고 합니다. 달리 말해 skill은 ‘이거 해줘’라고 가볍게 외치는 한마디가 아니라, 어느 정도 정리된 경험 한 묶음입니다.

이 느낌이 좋습니다.

팀의 지식이 없는 것은 아닙니다. 다만 아주 느슨한 형태로 존재할 때가 많다는 겁니다. 어떤 숙련된 엔지니어의 습관에 숨어 있거나, 한 번의 코드 리뷰 댓글에 들어 있거나, 단 한 번 언급된 내부 합의에 들어 있습니다. 물어보면 모두 조금씩 알고 있습니다. 정말 적어 보려 하면 늘 ‘이런 건 당연하죠’처럼 느껴집니다.

하지만 한 번 Agent에게 맡기게 되면, 많은 ‘당연한 일Suddenly 당연하지 않게 됩니다.

Agent는 디렉터리를 몇 개 변경했다는 사실이 무엇을 뜻하는지 처음부터 알지 못합니다.
어떤 종류의 변경은 완전히 검증해야 하고, 다른 종류의 변경에는 최소한의 검사만 하면 되는지도 모릅니다.
여러분이 변경 내용을 어떤 식으로 묘사하고, 다음 사람에게 맥락을 어떻게 넘기는지도 알지 못합니다.

그래서 skill의 의미가 어느새 분명해집니다.
경험을 대체하는 것이 아니라, 경험을 보존하는 것입니다.
새로운 절차를 만들어내는 것이 아니라, 원래 암묵적으로 유지되던 것들을 조금씩 재사용 가능한 형태로 만들어 내는 것입니다.

진짜 어려운 것은 ‘무엇을 할지’를 쓰는 것이 아니라, ‘언제 할지’를 쓰는 것입니다

OpenAI의 글에서 가장 계속 곱씹게 되는 부분은 skill description에 대한 강조입니다.

skill이 정말 쓸모 있는지 결정하는 것은 얼마나 완전하게 썼느냐가 아니라, 얼마나 정확하게 썼느냐입니다.
특히 ‘언제 트리거되어야 하는지’라는 경계가 중요합니다.

이 일은 얼핏 세부적인 문제처럼 보이지만, 사실 사람과 함께 일할 때와 매우 닮아 있습니다.
사람과 하는 협업이 매끄러워지게 만드는 것은 단계 자체만이 아니라, 언제 그 단계를 택할지입니다.

‘검증 절차를 실행해’라고만 말해도 틀리지는 않지만, 거의 도움이 되지 않습니다.
그다음에 가장 중요한 질문들은 아직 답해지지 않았으니까:

어떤 변경을 검증해야 하는 걸로 봅니다?
문서만 바꿨다면?
파일 이름만 변경했다면?
테스트나 빌드 파이프라인을 건드렸다면 더 엄격한 전체 검사로 바꿔야 할까요?
이 동작은 권고인가, 필수인가?

이 경계가 명확히 정해지지 않으면 skill은 쉽게 장식에 지나지 않습니다. 존재하지만 불안정하고, 가끔 호출되다가 가끔 무시됩니다. 마지막 문제는 모델에 있지 않습니다. 이 능력이 자기 등장 시점을 제대로 정의하지 못한 데 있습니다.

skill을 쓰는 것은 어느 정도 가벼운 제도를 만드는 것과 비슷합니다.
제도는 말투가 강한 게 아니라, 경계가 분명해서 유지됩니다.
무엇을 언제 해야 하고, 언제 하지 않아야 하며, 무엇이 예외인지, 무엇은 반드시 실행해야 하는지가 분명해지면, 뒤따르는 절차는 오히려 단순해집니다.

저장소에는 사실 늘 ‘Agent를 위해 쓰는 문서’가 부족했습니다

글에서는 AGENTS.md를 언급했습니다. 이 구성 방식도 마음에 듭니다.

조금 past 우리가 새 동료에게 쓰던 온보딩 문서와 비슷합니다. 다만 이번에 읽는 사람이 사람이 아니라 Agent라는 점이 다릅니다.

저장소에는 저마다의 성격이 있습니다.
디렉터리 구조는 어떻게 나뉘는지, 어느 곳이 핵심 경로인지, 어떤 규칙은 눈에 잘 띄지 않지만 건드릴 수 없는지, 일부 모듈의 테스트를 왜 이렇게 돌려야 하는지, 특정 API의 동작은 소스 코드와 문서 중 무엇을 믿어야 하는지 모두 저장소 내부의 언어입니다.

평소에는 사람이 이를 이해하는 데 의존해도 큰 문제는 없습니다. 사람은 짐작하고, 질문하고, 맥락을 따라가며 많은 암묵적 정보를 채워냅니다.
하지만 Agent는 조금 다릅니다. 물론 추론은 할 수 있지만, 가장 두려워하는 것은 ‘누구나 당연히 알고 있으면서도 아무도 진지하게 적어 두지 않은 것’입니다.

그래서 AGENTS.md는 문서가 하나 더 늘었다는 느낌보다, ‘원래는 진작에 적혀 있어야 했던’ 저장소 내 합의를 받아 줄 명확한 형태가 생겼다는 느낌을 줍니다.

AGENTS.md가 전체 설명에 가깝다면, skill은 개별 업무 흐름에 가깝습니다.
전자는 ‘어떤 종류의 장소인지’를, 후자는 ‘여기서 어떤 일을 어떻게 해야 하는지’를答해 줍니다.

그 아래에는 GitHub Actions처럼 더 확실한 자동화 안전장치도 있습니다.
이렇게 층층이 내려다보면, 이 구조가 꽤 자연스럽게 이어집니다.

사람은 경험을 만들고,
문서는 경험을 표현하며,
skill은 경험을 호출하고,
스크립트와 CI는 경험을 실행합니다.

제가 예전에 상상한 ‘AI가 엔지니어링을 바꾼다’는 그림과는 꽤 다릅니다. 특별히 극적인 변화도 없고, 오히려 소프트웨어 엔지니어링이 오랫동안 익숙해 온 길과 닮아 있습니다. 불안정한 수작업을 점차 안정적인 시스템 동작으로 정리해 나가는 것이지요.

모델이 모든 일을 할 필요는 없습니다

이 글에는 제가 크게 공감하는 판단도 하나 있습니다. 모델이 모든 일을 맡아서는 안 됩니다.

말로 하면 간단하지만, 실제로 해 보면 욕심이 쉽게 납니다.
모델이 모든 것을 처리할 수 있어 보이니, 이해와 판단과 실행과 출력 형식 정리를 한꺼번에揉어 모델에게 넘기게 됩니다.

결과는 대체로 좋지 않습니다.

맥락을 이해하고, 비교하고, 요약하고, 판단하는 일에는 모델이 잘 맞습니다.
하지만 정해진 순서대로 명령을 실행하고, 상태를 수집하고, 예측 가능한 결과를 내는 일은 본질적으로 스크립트가 더 적합합니다.

이 경계가 정리되면, 많은 설계 문제도 자연스럽게 풀립니다.

예를 들어 변경이 동작 변경인지 판단하려면 모델이 필요합니다. diff를 읽고, 의도를 이해하고, 주변 맥락도 파악해야 합니다.
하지만 ‘먼저 어떤 명령을 실행할지, 실패를 어떻게 요약할지, git 상태와 브랜치 정보를 어디에서 수집할지’ 같은 것은 최대한 스크립트에 맡겨야 합니다.

좋은 시스템은 능력을 한곳에 쌓는 대신, 각자의 책임을 분리합니다.
모델은 본래 불확실한 부분을 담당합니다.
스크립트는 최대한 확실해야 할 부분을 담당합니다.

Skill이 ‘엔지니어링’에 더 가깝게 느껴지는 이유도 여기에 있습니다. 모델을 만능한 주체로 상상하지 않고, 진정으로 안정적인 업무 흐름은 단일 능력의 팽창이 아니라 서로 다른 능력의 협업에서 나온다는 사실을 인정하기 때문입니다.

결국 Skills가 정리하는 것은 ‘암묵적 경험’입니다

뒤로 더 생각해 볼수록, Skills에서 가장 소중한 부분은 효율을 얼마나 높여 주는지가 아니라, 평소 인정하기 싫었던 사실, 즉 우리의 많은 업무가 암묵적 경험에 기반한다는 사실을 팀이 마주하도록 만들었다는 데 있을지도 모릅니다.

이런 경험은 평소 부족해 보이지 않습니다.
항상 누군가는 알고 있으니까.
팀에는 늘 저장소와 절차, ‘쓸어놓지는 않았지만 모두가 하는’ 것들에 정통한 사람들이 있기 때문입니다. 그래서 문제는 늘 해결되는 것처럼 보이고, 절차도 늘 잘 굴러가는 것처럼 보입니다.

하지만 팀이 커지고 프로젝트가 복잡해지거나 Agent가 들어오면, 이 암묵적인 부분들이 바로 드러납니다.

AI는 팀의 암묵적 합의를 자동으로 물려받지 않습니다.
원래 말할 필요가 없다고 여기는 규칙도 자연스럽게 이해하지 못합니다.

그때부터는 예전에 친숙한 사람들의 관계망이 조용히 삼켜 주던 문제도 하나씩 분명하게 말해야 합니다:

무엇은 반드시 해야 합니까?
무엇이 단지 권고입니까?
어떤 단계는 반드시 자동화해야 합니까?
어떤 판단은 여전히 사람이 해야 합니까?
어떤 지식은 채팅 기록에 남겨 두는 대신 저장소에 적어야 합니까?

Skills는 표면적으로는 Agent를 돕지만, 실제로는 팀이 자신을 다시 인식하게 돕습니다.
여러분은 구체적으로 어떤 방식으로 일하는지.
어떤 경험은 다른 곳으로 옮겨 적용할 수 있는지.
어떤 절차는 표준으로 남길 가치가 있는지.
개인 기억에 의존하던 어떤 부분은 진작에 대체했어야 할지.

이 관점에서 단순한 새 기능이 아니라 아주 조용한 정돈 과정 같다는 생각이 듭니다.

저는 어디서 시작할까요

만약 저장소에서 skill을 조금씩 만들어 나간다면, 저는 처음부터 거대한 시스템을 설계하지는 않을 것 같습니다.

대신 이미 충분히 반복되고, 충분히 명확하며, 실패 비용도 낮지 않은 일부터 시작하고 싶습니다.

예를 들어 검증 절차입니다.
변경 후 무엇을 어떤 순서로 실행할지, 어떤 경우 추가 검사가 필요한지, 실패했을 때 결과를 어떻게 명확히 설명할지 같은 것들을 skill에 담기 좋습니다. 사용 빈도가 높고 반복적인 일이어서, 기억에 의존하기만 하면 특히 빠지기 쉽기 때문입니다.

다음으로 PR 정리 작업도 그렇습니다.
제목은 어떻게 정하고, 변경 사항은 어떻게 요약하고, 영향 범위는 어떻게 설명하고, 검증 방식을 어떻게 적어야 리뷰어가 수월한지 정하는 일입니다. 이런 일 자체는 어렵지 않지만 집중력을 꽤消耗합니다. 좋은 draft가 있으면 설명을 오가는 과정을 많이 줄일 수 있습니다.

문서 확인도 마찬가지입니다.
OpenAI는 글에서 플랫폼이나 API 동작을 다룰 때, Agent에게 현재 문서를 확인하게 하고 기억에 의존해 답하지 않게 한다고 언급했습니다. 이 원칙이 마음에 듭니다. 빠르게 변하는 것들은 ‘내 기억으로는 이랬던 것 같은데’라는 태도가 가장 위험합니다. ‘답하기 전에 먼저 문서를 확인한다’를 기본 동작으로 바꾸는 것은, 본질적으로 시스템에 꼭 필요한 제약을 부여하는 일입니다.

그다음은 출시 전 검사일 수도 있습니다.
이런 절차가 매일 진행되는 것은 아니지만, 한 번 잘못되면 대개 큰 후회를 하게 됩니다. 버전 번호, changelog, 예제가 실행 가능한지, release note 초안, breaking changes 확인 같은 것들을 조금씩 축적해 둘 수 있습니다.

공통점은 창작적인 일이 아니라 반복적인 일이라는 점입니다.
그렇기에 더 저장소에 적어 둘 가치가 있습니다.

왜 이 일에 조금씩 낙관적으로 느꼈을까요

요즘 몇 년간 AI를 둘러싼 이야기도 많았고, 시끌시끌한 것도 많았습니다.
그런데 시간이 갈수록 저는 오히려 조용한 것들에 더 매력을 느낍니다. 모델이 또 어떤 benchmark를 깨뜨렸거나, Agent가 얼마나 복잡한 작업을 완수한 것이 아니라, Skills처럼 눈에 잘 띄지는 않지만 실제 업무 현장에 아주 가까운 설계가 말입니다.

AI가 엔지니어링에 진정으로 들어오는 일은, 한 번의 극적인 대체보다 이런 완만한 침투를 통해 이루어질 가능성이 더 큽니다. 먼저 작은 절차 하나를 담아내고, 업무 습관 하나를 담아내며, 경험 안에만 있던 방식 하나를 조금씩 저장소의 일부로 바꾸는 식으로요.

이 접근이 매력적인 이유는 새로운 신화를 만드는 것이 아니라, 원래부터 가치 있던 것들을 보존하기 때문입니다.

우리는 늘 소프트웨어 엔지니어링이 손에 익힌 경험을 시스템화한다고 말해 왔습니다.
어떤 의미에서 Skills는 이 말을 한 걸음 더 밀고 나간 것에 불과합니다.

예전에는 경험을 문서로, 스크립트로, CI로 적었습니다.
이제는 경험을 Agent도 이해하고 사용할 수 있는 능력으로 작성해 보려 합니다.

이런 변화가 좋습니다.

이제야 Agent가 엔지니어링 체계에 갑자기 끼어든 외부자가 아니라는 생각이 듭니다.
새로운 참여자처럼 보입니다.
그리고 새로운 참여자에게 가장 중요한 것은 ‘Agent가 얼마나 많은 일을 할 수 있는가’가 아니라 ‘우리가 자신의 업무 방식을 Agent에게 진지하게 알려 주려 하는가’입니다.

결국 skill은 모델에게 일을 하는 법을 가르치는 것이 아닙니다.
먼저 우리가 구체적으로 어떻게 일하는지 분명히 생각해 보게 합니다.