AI 코딩 에이전트에게 긴 규칙보다 짧은 가드가 필요했던 이유

AI 코딩 에이전트에게 규칙을 길게 주면 더 안전해질 줄 알았습니다. 실제로는 꼭 그렇지 않았습니다. 규칙이 길어질수록 에이전트가 더 조심스러워지는 대신, 질문이 늘거나, 작업이 커지거나, 본래 요청과 상관없는 정리까지 같이 하려는 순간이 있었습니다.

제가 원한 것은 “더 똑똑한 개발자처럼 행동해줘”가 아니었습니다. 작은 요청을 작게 끝내고, 끝났다고 말하기 전에 확인하고, 모르면 멈출 수 있는 보조자에 가까웠습니다.

최근 andrej-karpathy-skills라는 이름으로 돌아다니는 코딩 에이전트 가이드 repo를 wiki에 검토했습니다. 이름만 보면 Karpathy 본인의 공식 배포물처럼 오해할 수 있지만, 제가 본 자료는 제3자 repo와 개인 블로그 해설이 섞인 참고 자료였습니다. 그래서 그대로 설치하지 않고, Daejin Lab에서 쓸 수 있는 짧은 행동 가드로 바꿔 보았습니다.

이 글은 그 기록입니다. “이 repo를 설치하세요”가 아니라, AI 코딩 에이전트에게 어떤 짧은 기준을 남기면 작업이 덜 흔들렸는지 적어둡니다.

작은 요청이 큰 리팩터링으로 번지는 문제

에이전트에게 이런 요청을 던질 때가 있습니다.

이 버튼 문구만 조금 자연스럽게 바꿔줘.

사람이 보면 작은 작업입니다. 그런데 AI 코딩 에이전트는 가끔 주변 구조까지 같이 고치려 합니다. 버튼 문구를 바꾸다가 컴포넌트를 나누고, 스타일 이름을 정리하고, 테스트 이름을 바꾸고, 사용하지 않는 파일을 건드리는 식입니다.

결과만 보면 “개선”처럼 보일 수 있습니다. 하지만 개인 프로젝트에서는 이런 변경이 피곤합니다.

제가 요청하지 않은 파일까지 diff에 들어옵니다.
빌드가 깨졌을 때 원인 범위가 넓어집니다.
리뷰할 때 “이 줄은 왜 바뀌었지?”를 다시 확인해야 합니다.
나중에 되돌릴 때 작은 작업 하나가 큰 revert가 됩니다.

Daejin Lab에서도 블로그 작업에 이 기준을 그대로 두었습니다. 글 하나를 다듬는 요청이 사이트 구조, SEO 설정, 내부 링크까지 같이 바뀌면 좋아 보여도 검토 비용이 늘어납니다. 그래서 짧은 가드를 먼저 세우는 쪽이 더 낫다고 느꼈습니다.

짧은 가드레일 설계 이유: 긴 규칙은 읽고 지나가는 속도가 빠르다 → 질문 형태의 경계 → 승인 요청 구간 고정 → 결과를 기록으로 남김으로 이어지는 다이어그램

이 카드는 짧은 가드가 반복 가능한지 확인하는 설계 기준입니다.

짧은 가드레일은 목표, 단순성, 변경 범위, 검증으로 이어진다

제가 뽑아낸 4가지 행동 가드

검토한 가이드의 핵심은 크게 네 문장으로 줄일 수 있었습니다.

가드	제가 이해한 뜻	Daejin Lab식 적용
Think before coding	바로 고치기 전에 가정과 위험을 본다	모호하지만 결과가 달라지는 부분만 짚는다
Simplicity first	필요 이상의 구조를 만들지 않는다	한 번 쓰는 코드는 한 번 쓰는 형태로 둔다
Surgical changes	요청과 직접 관련된 줄만 바꾼다	인접 리팩터링은 별도 후보로만 남긴다
Goal-driven verification	완료 기준 없이 끝났다고 말하지 않는다	빌드, 테스트, diff, leak check 중 맞는 검증을 붙인다

처음에는 이 네 가지가 너무 당연해 보였습니다. 그런데 실제로는 이 당연한 말이 없을 때 에이전트가 가장 많이 흔들렸습니다.

특히 Surgical changes가 중요했습니다. AI 코딩 도구는 “더 좋은 구조”를 만들고 싶어 하는 방향으로 움직일 때가 있습니다. 하지만 지금 필요한 것이 문구 수정이면, 더 좋은 구조가 아니라 문구 수정만 끝내는 게 맞습니다.

Think before coding은 질문을 많이 하라는 뜻이 아니었습니다

이 부분이 제일 조심스러웠습니다.

“코딩 전에 생각하라”를 그대로 적용하면 에이전트가 매번 질문부터 할 수 있습니다.

어떤 톤을 원하시나요?
어떤 파일을 수정할까요?
테스트 범위는 어디까지인가요?
이 방향으로 진행해도 될까요?

물론 위험한 작업에서는 질문이 필요합니다. 하지만 모든 작업에서 질문만 늘어나면, 사용자는 AI에게 일을 맡기는 것이 아니라 AI를 계속 관리하게 됩니다.

그래서 Hermes식으로는 이렇게 바꿨습니다.

기본값이 obvious하면 진행한다.
결과물, 범위, 위험이 달라지는 모호성만 질문한다.

예를 들어 오타 수정, 짧은 문장 다듬기, 명확한 테스트 실행은 바로 진행해도 됩니다. 반대로 아래 같은 일은 멈춰야 합니다.

파일을 대량 이동해야 할 때
public site에 영향을 줄 때
git push나 배포가 연결될 때
API key, OAuth, 결제, 외부 계정 설정이 걸릴 때
법률·투자·의료처럼 책임 있는 판단으로 보일 때

저는 이 차이를 “질문을 잘하는 AI”보다 “멈출 곳을 아는 AI”에 가깝다고 봅니다.

질문이 필요한 경우와 바로 진행해도 되는 경우를 나누는 기준

Simplicity first는 멋진 설계를 참는 일에 가까웠습니다

AI 에이전트는 가끔 미래를 너무 빨리 봅니다. 아직 한 번만 쓰는 기능인데 config를 만들고, interface를 만들고, provider abstraction을 만들고, 나중에 쓸 수도 있는 확장점을 준비합니다.

개발자로 보면 좋은 습관처럼 보이기도 합니다. 하지만 개인 프로젝트에서는 미래 확장성보다 오늘의 검증 가능성이 더 중요할 때가 많았습니다.

제가 정한 기준은 단순합니다.

오늘 요청된 요구가 아니면 만들지 않는다.
반복이 실제로 보일 때까지 추상화하지 않는다.
새 설정은 삭제/rollback 경로가 있을 때만 추가한다.

Daejin Lab 블로그도 마찬가지였습니다. 처음부터 CMS, admin, 자동 발행 대시보드까지 붙이는 대신 Astro Markdown과 publish guard로 버텼습니다. 불편한 부분은 있었지만, 덕분에 어떤 글이 공개되는지 직접 볼 수 있었습니다.

AI 코딩 에이전트에게도 같은 태도가 필요했습니다. “좋은 아키텍처”를 만드는 일보다 “지금 요청한 작은 목표를 깨지지 않게 끝내는 일”이 먼저였습니다.

Surgical changes는 diff를 작게 만드는 규칙입니다

제가 제일 자주 확인하는 질문은 이것입니다.

이 변경된 줄은 사용자 요청과 직접 연결되는가?

대답이 애매하면 보류합니다. 정말 필요해 보여도 같은 PR이나 같은 작업에 섞지 않습니다.

예를 들어 버튼 문구를 고치다가 타입 이름이 마음에 안 들 수 있습니다. 오래된 주석이 눈에 보일 수도 있습니다. CSS class 순서가 지저분할 수도 있습니다. 그래도 지금 요청이 버튼 문구라면, 그 작업은 다음 후보로 남기는 편이 안전했습니다.

이 규칙은 블로그 글에도 그대로 적용됩니다.

글 하나를 쓰는 요청이면, 사이트 구조를 같이 바꾸지 않습니다.
draft 글을 만드는 요청이면, draft:false 전환을 같이 하지 않습니다.
검증을 하는 요청이면, Search Console이나 AdSense 콘솔을 누르지 않습니다.
내부 wiki를 참고해도, private raw 경로나 불필요한 내부 ID를 공개 글에 넣지 않습니다.

작게 바꾸면 검증도 쉬워집니다. 검증이 쉬우면 제가 다시 읽을 때 덜 피곤합니다.

Goal-driven verification은 “완료했습니다”를 믿지 않는 장치입니다

AI 에이전트가 “완료했습니다”라고 말하는 순간에도 저는 한 번 더 봅니다. 말은 쉽게 끝나지만, 실제 작업은 파일과 빌드와 diff에 남기 때문입니다.

그래서 요청을 줄 때 가능하면 완료 기준을 같이 둡니다.

목표: 새 블로그 draft를 만든다.
제약: draft:true, push 금지.
검증: npm run verify:publish 통과, sitemap/RSS에 draft slug 없음.

코드 작업이면 조금 다르게 둡니다.

목표: 특정 테스트 실패를 고친다.
제약: 관련 파일만 수정한다.
검증: 실패하던 테스트와 전체 테스트 중 필요한 범위를 다시 돌린다.

검증은 거창할 필요가 없습니다. 작은 작업이면 git diff --check 하나만으로도 의미가 있습니다. 중요한 것은 “좋아 보인다”에서 끝내지 않는 것입니다.

Daejin Lab에서는 이 기준이 꽤 도움이 됐습니다. 글을 쓰고 나면 draft가 production에 새지 않았는지 보고, 공개 글이면 sitemap과 RSS에 들어갔는지 확인합니다. AI가 쓴 문장이 자연스러운지도 중요하지만, 공개 표면이 의도와 맞는지가 더 중요했습니다.

긴 규칙보다 짧은 가드가 잘 먹히는 이유

긴 규칙이 나쁜 것은 아닙니다. 프로젝트가 커질수록 AGENTS.md, publish guard, coding convention, test policy 같은 문서는 필요합니다.

다만 작업 중 에이전트에게 계속 들려줄 행동 규칙은 짧을수록 잘 작동하는 느낌이었습니다. 제가 자주 쓰고 싶은 형태는 이 정도입니다.

1. 먼저 목표와 위험한 가정을 짧게 확인한다.
2. 요청된 것보다 크게 만들지 않는다.
3. 관련 있는 줄만 바꾼다.
4. 끝났다고 말하기 전에 검증한다.

이 네 줄이면 에이전트가 초보자처럼 아무것도 못 하지는 않습니다. 동시에 마음대로 큰 구조를 만들지도 않습니다.

무엇보다 제 태도도 바뀝니다. “AI가 잘해주겠지”가 아니라, “이번 작업의 목표와 검증은 무엇이지?”를 먼저 보게 됩니다.

제가 원하는 AI 코딩 에이전트의 태도

지금 기준으로 제가 원하는 AI 코딩 에이전트는 천재 개발자보다 조심스러운 작업자에 가깝습니다.

모르면 모른다고 말합니다.
obvious한 일은 바로 진행합니다.
위험한 일은 멈춥니다.
요청보다 큰 리팩터링을 하지 않습니다.
검증하지 못한 부분을 완료처럼 말하지 않습니다.
공개, 결제, 계정, 배포 버튼은 사람에게 남깁니다.

이런 태도가 있으면 에이전트를 조금 더 편하게 쓸 수 있습니다. 반대로 이 선이 없으면, 결과물이 좋아 보여도 제가 계속 불안해집니다.

결국 저는 AI 코딩 에이전트에게 더 긴 규칙을 주고 싶었던 것이 아니었습니다. 짧은 가드 안에서 움직이길 원했습니다. 작은 요청은 작게 끝내고, 큰 결정은 사람에게 남기고, 끝난 뒤에는 검증 흔적을 보여주는 도구. 지금은 그 정도가 개인 프로젝트에서 가장 현실적인 기준이라고 보고 있습니다.

출처와 기준일

기준일: 2026-05-26
내부 wiki: Andrej Karpathy Skills Absorption Review 2026-05-24
검토한 외부 자료: multica-ai/andrej-karpathy-skills GitHub repo와 관련 개인 블로그 해설
출처 품질: GitHub repo 원문은 B, 개인 블로그 해설은 C로 보았습니다.
주의: 이 글은 해당 repo 설치 권장이 아닙니다. Daejin Lab/Hermes 작업 방식에 맞게 원칙만 재해석한 운영 기록입니다.

2026-05-31에 다시 본 짧은 가드레일의 역할

AI 코딩 에이전트 가드레일은 길게 쓴다고 안전해지는 것이 아니었습니다. 오히려 짧고 반복해서 지킬 수 있어야 실제 작업에서 작동했습니다. 이번 AdSense 보강에서도 범위, 금지, 검증, 승인이라는 네 가지 선을 계속 반복해서 봤습니다.

참고한 공식 문서

확인하지 않은 것

이 글은 모든 프로젝트의 보안 정책을 대체하지 않습니다. 개인 프로젝트에서 AI 코딩 에이전트와 같이 일할 때 최소한으로 남겨야 할 운영선입니다.

FAQ

가드레일은 길수록 좋은가요?

아닙니다. 실제로 읽히고 반복 적용되는 짧은 규칙이 더 낫습니다.

가장 먼저 써야 할 가드레일은 무엇인가요?

수정 범위, 비밀값 금지, 테스트 명령, 발행 승인선입니다.

블로그 보강과 어떤 관련이 있나요?

여러 글을 고칠 때도 같은 규칙이 있어야 민감정보 노출과 검증 누락을 줄일 수 있습니다.