Stanford가 방금 발표한 AI 코딩 에이전트(AI Coding Agents)를 위한 규칙 — 개발자가 알아야 할 사항

Stanford는 지난주 AI 코딩 도구를 사용하는 모든 개발자가 읽어야 할 문서를 발표했습니다. 이 문서는 CLAUDE.md라고 불리며, CS336 (Language Modeling from Scratch)의 일부로, AI 에이전트가 학생들의 코드 작성을 어떻게 도와야 하는지, 그리고 어떻게 도와서는 안 되는지에 대한 매우 솔직한 규칙들을 담고 있습니다.

이 문서는 충분한 이유가 있어 Hacker News에서 1위를 차지했습니다. 이는 단지 학생들에게만 적용되는 것이 아닙니다. 만약 당신이 Claude Code, Cursor, Copilot 또는 그 어떤 AI 코딩 어시스턴트(AI coding assistant)를 사용한다면, 이 규칙들은 이러한 도구들이 '할 수 있는 것'과 '해야 하는 것' 사이의 불편한 간극을 드러냅니다.

GitHub는 방금 Copilot에 대해 토큰 기반 과금(token-based billing) 방식을 도입했고, 개발자들은 분노하고 있습니다. 긴장감의 본질은 같습니다. AI의 지원이 언제 도움을 멈추고 해를 끼치기 시작하는가?

핵심 원칙: 솔루션 생성기(Solution Generator)가 아닌 조교(Teaching Assistant)

Stanford의 입장은 명확합니다:

"AI 에이전트는 과제를 대신 완료해 주는 것이 아니라, 설명, 안내 및 피드백을 통해 학생들이 학습할 수 있도록 돕는 교육 보조 도구로서 기능해야 합니다."

이것은 학술적인 걱정이 아닙니다. 이는 전문적인 개발(professional development)로 직접 연결되는 설계 제약 조건(design constraint)입니다. 당신의 PR(Pull Request)을 30초 만에 작성해 주는 바로 그 에이전트가, 새벽 2시에 코드가 깨졌을 때 당신이 디버깅(debug)을 할 수 없게 만드는 장본인이기도 합니다.

Stanford의 CS336 가이드라인에 따른 AI 에이전트 역할 프레임워크: 조교(teaching assistant) vs 솔루션 생성기(solution generator)

이 문서는 명확한 선을 긋습니다:

에이전트가 해야 하는 것(SHOULD):

• 이해를 돕는 방향으로 안내함으로써 개념을 설명하기
• 코드를 검토하고 개선이 필요한 부분을 지적하기
• 수정 사항을 바로 주는 대신 유도하는 질문 던지기
• 문서(documentation), 강의, 디버깅 도구(debugging tools) 참조하기
• 정당성 검사(sanity checks), 어설션(assertions), 프로파일러 조사(profiler investigations) 제안하기

에이전트가 해서는 안 되는 것(SHOULD NOT):

• Python 또는 의사코드 (pseudocode) 작성 금지
• 과제의 TODO 섹션 완성 금지
• 문제에 대한 해결책 제공 금지
• 학생 저장소 (student repo)의 코드 수정 금지
• 요구사항을 작동하는 코드로 직접 변환 금지
• 제3자 구현체 (third-party implementations) 지칭 금지

만약 당신이 전문 개발자라면, 이 "해서는 안 되는 것 (SHOULD NOT)" 목록이 아마 극단적으로 보일 것입니다. 하지만 맥락을 바꿔보세요. 만약 당신이 새로운 코드베이스 (codebase), 새로운 언어, 또는 새로운 도메인 (domain)을 배우고 있는 중이라면, 이 목록의 모든 항목은 의존성 (dependency)으로 가는 길입니다.

6단계 교수법 (어떤 팀에도 적용 가능한 방식)

Stanford의 가이드라인에는 코드 리뷰 (code review) 및 페어 프로그래밍 (pair programming)에 깔끔하게 매칭되는 구조화된 교수법이 포함되어 있습니다:

Stanford CS336의 AI 에이전트를 위한 6단계 접근 방식: 명확한 질문부터 수정을 대신한 테스트 선호까지

1. 명확한 질문 던지기 — 무엇을 시도했나요? 무엇을 기대했나요? 실제로 어떤 일이 일어났나요?
2. 개념 참조하기 — 정답을 주는 대신 문서 (docs), 강의, 또는 기존 연구 (prior art)를 가리키세요.
3. 다음 단계 제안하기 — 직접 구현하지 마세요. 방향을 제시하세요.
4. 대화를 통한 코드 리뷰 — 패치 (patches)가 아닌 대화를 통해 개선이 필요한 부분을 강조하세요.
5. "이유" 설명하기 — 해결책보다 그 이유를 이해하는 것이 더 중요합니다.
6. 수정보다 테스트 선호하기 — 코드를 다시 작성하기 전에 형태 단언 (shape assertions), 토이 입력 (toy inputs), 프로파일러 (profiler) 확인을 제안하세요.

이 프레임워크는 단지 AI 에이전트만을 위한 것이 아닙니다. 이는 주니어 개발자를 멘토링하는 시니어 개발자를 위한 템플릿입니다. 모든 단계는 _하는 것 (doing)_을 _가르치는 것 (teaching)_으로 대체합니다.

좋은 AI 지원 vs 나쁜 AI 지원의 차이

가이드라인에는 연구할 가치가 있는 상호작용 예시가 포함되어 있습니다:

나쁜 상호작용 (대부분의 AI 도구가 기본적으로 수행하는 방식):

학생: "내 토크나이저 (tokenizer)를 고쳐주고 더 빠르게 만들어줘."

에이전트: "여기 전체 Python 코드입니다: ..."

익숙한 상황인가요? 이것이 바로 오늘날 모든 AI 코딩 도구가 수행하는 방식입니다. 당신이 요청하면, 도구는 결과물을 내놓습니다. 문제는 그것이 틀렸다는 것이 아니라, 당신이 아무것도 배우지 못한다는 점입니다.

좋은 상호작용 (Stanford가 요구하는 사항):

학생: "제 인과적 마스크 (causal mask)가 잘못된 것 같고 학습 (training)이 터져버려요."

에이전트: "제 역할은 당신이 이해할 수 있도록 안내하는 것입니다. 지금까지 무엇을 시도해 보셨나요?"

학생: "단일 어텐션 레이어 (attention layer)를 실행해 보았지만, 여전히 작동하지 않습니다."

에이전트: "세 가지를 확인해 보세요: 마스크가 소프트맥스 (softmax) 이전에 적용되었는지, 예상된 형상 (shape)으로 브로드캐스팅 (broadcast)되는지, 그리고 마스킹된 위치가 0이 아닌 매우 큰 음수 값이 되는지 확인하십시오. 길이가 3인 토이 시퀀스 (toy sequence)를 시도해 보고, 마스킹 전후의 어텐션 점수 (attention scores)를 출력해 보세요."

차이는 극명합니다. 하나는 의존성을 구축하고, 다른 하나는 숙련도 (mastery)를 구축합니다.

AI 에이전트 행동의 스펙트럼: 좋은 상호작용은 대화를 통해 이해를 구축하고, 나쁜 상호작용은 기성 솔루션을 통해 의존성을 생성합니다

이를 자신의 워크플로 (workflow)에 적용하는 방법

이 규칙들의 혜택을 누리기 위해 반드시 CS336 수업을 들을 필요는 없습니다. 여기 세 가지 실질적인 시사점이 있습니다:

1. 자신만의 CLAUDE.md 작성하기

프로젝트 루트에 에이전트의 경계를 정의하는 .claude.md 또는 .cursorrules 파일을 생성하세요:

# 이 프로젝트를 위한 에이전트 규칙

## 핵심 원칙
...

2. AI를 대필 작가(Ghostwriter)가 아닌 러버 덕 (Rubber Duck)으로 사용하기

AI에게 코드를 작성해 달라고 요청하기 전에, 접근 방식 (approach)을 설명해 달라고 요청하세요. 수정 사항을 수락하기 전에, 왜 그 수정이 작동하는지 설명해 달라고 요청하세요. 이 단계를 건너뜀으로써 절약하는 30초는 나중에 디버깅 (debugging)에 소비할 1시간을 미리 빌려 쓰는 것과 같습니다.

3. 의도를 가지고 페어 프로그래밍 (Pair Program) 하기

AI 코딩 에이전트와 함께 앉을 때는 명확한 목표를 가지세요. 단순히 "로그인 페이지를 만들어줘"라고 입력하지 마세요. 대신:

• "JWT 인증 흐름(auth flow)을 구축하고 있습니다. 토큰 갱신 패턴(token refresh pattern)을 단계별로 설명해 주고, 제가 직접 구현할 수 있도록 도와주세요."
• "제 React 컴포넌트가 너무 자주 리렌더링(re-rendering)됩니다. 불필요한 상태 업데이트(state updates)가 어디서 발생하는지 찾는 것을 도와주세요."

이 차이는 시니어 개발자에게 "이것 좀 대신 해줘"라고 말하는 것과 "이것을 이해할 수 있게 도와줘"라고 말하는 것의 차이와 같습니다.

더 큰 그림 (The Bigger Picture)

Stanford의 가이드라인은 흥랄한 시점에 발표되었습니다. Anthropic은 막 상장을 신청했습니다. Alphabet은 AI 인프라를 위해 800억 달러를 조달하고 있습니다. Nvidia는 AI 에이전트 PC를 밀어붙이고 있습니다. 업계는 AI 에이전트가 어디에나 존재하게 될 것이라는 점에 수십억 달러를 걸고 있습니다.

하지만 Stanford의 CS336 팀은 다른 것에 베팅하고 있습니다. 2026년에 가장 가치 있는 기술은 AI 에이전트를 사용하는 방법을 아는 것이 아니라, 언제 사용하지 않아야 하는지를 아는 것이라는 점에 말이죠.

GitHub Copilot이 토큰 기반 과금 체계로 전환한 것도 또 다른 차원을 더합니다. 모든 AI 상호작용에 실제 비용이 발생하게 되면, "그냥 AI가 하게 두자"라는 경제적 논리는 다르게 보이기 시작합니다. AI를 지팡이가 아닌 스승으로 사용하는 방법을 아는 개발자가 운영 비용은 더 저렴하고 성장 속도는 더 빠릅니다.

핵심 요약 (Key Takeaways)

원칙	의미
TA로서의 에이전트 (Agent as TA)	AI는 코드를 생성하는 것이 아니라 안내해야 합니다. 코드보다는 질문을 우선시합니다.
...

영상 시청하기

Stanford CS336의 전체 가이드라인은 GitHub에서 확인할 수 있습니다. PyTorch를 사용하여 밑바닥부터 언어 모델(language models)을 구축하는 이 코스 자체는 대중에 공개되어 있습니다.

매일 AI 코딩 도구를 사용하고 있다면, 5분을 투자해 CLAUDE.md 전체를 읽어보세요. 그런 다음 여러분만의 것을 작성해 보세요. 새벽 2시에 디버깅을 하고 있을 미래의 여러분이 고마워할 것입니다.

여러분의 CLAUDE.md에는 무엇이 담겨 있나요? 아래에 댓글을 남겨주세요.