AI가 당신의 코드베이스를 망치지 않게 하는 법: 의도적인 AI 코딩 가이드

Who Should Read

AI 코딩 에이전트(Cursor, Copilot 등)를 일상적으로 사용하면서 코드베이스 품질 저하를 걱정하는 백엔드/풀스택 개발자나 팀 리드.

Core Mechanics

• AI가 코드를 나쁘게 짜는 게 문제가 아니라, 팀이 충분히 소화하기도 전에 코드가 너무 빠르게 쌓이는 게 진짜 문제다. 명백한 버그보다 일관성이 서서히 무너지는 조용한 침식이 더 위험하다.
• Semantic Function(의미 함수)은 코드베이스의 최소 단위 빌딩 블록이다. 필요한 입력만 받고, 필요한 출력만 돌려주고, 사이드 이펙트 없이 그 이름이 말하는 일만 해야 한다. `quadratic_formula()`나 `retry_with_exponential_backoff_and_run_y_in_between()` 같은 식으로 이름 자체가 동작을 설명해야 하며, 별도 주석 없이도 이해 가능해야 한다.
• Pragmatic Function(실용 함수)은 여러 Semantic Function과 복잡한 로직을 묶는 래퍼다. `provision_new_workspace_for_github_repo(repo, user)` 같은 형태로 프로덕션 수준의 복잡한 프로세스를 담당하며, 시간이 지나면 내부가 완전히 바뀔 수 있어서 doc comment를 달아두되 함수 이름의 재진술이 아니라 '잔액이 10 미만이면 early fail' 같은 예외적 동작만 기록해야 한다.
• 데이터 모델 설계에서 옵셔널 필드는 그 데이터를 다루는 모든 코드가 매번 '이 필드가 있는지 없는지'를 체크해야 하는 부담을 준다. 잘못된 상태(wrong state)가 아예 만들어지지 않도록 모델 자체가 제약을 강제해야 하고, 버그는 로직 깊은 곳이 아닌 데이터 생성 시점에 터져야 한다.
• 모델 이름은 `UnverifiedEmail`, `PendingInvite`, `BillingAddress`처럼 어떤 필드가 속하는지 바로 알 수 있을 만큼 정밀해야 한다. `BillingAddress`에 `phone_number` 필드가 있으면 이미 모델이 너무 많은 역할을 하고 있다는 신호다.
• 같은 형태(`{ id: String }`)여도 `DocumentReference`와 `MessagePointer`처럼 완전히 다른 도메인 개념일 수 있다. Brand Type(브랜드 타입, 같은 구조라도 타입 수준에서 구분하는 기법)을 활용하면 함수가 잘못된 타입을 조용히 수용하는 문제를 컴파일 타임에 잡을 수 있다.
• 이 가이드는 `npx skills add theswerd/aicode` 명령으로 AI 에이전트에게 직접 스킬로 주입할 수 있다. 인간이 리뷰 후에 의도를 더하는 게 아니라, 프롬프트 전에 AI가 따를 규칙을 미리 심어두는 방식이다.

Evidence

• '옵셔널 필드를 남발한다'는 지적에 많은 공감이 있었다. 한 개발자는 AI 코드 리뷰의 첫 번째 단계로 AI가 추가한 옵셔널 인자들을 전부 찾아보는 습관을 들였다고 했고, 제대로 설계됐다면 옵셔널이 필요 없었을 자리에 옵셔널이 붙어 있는 경우가 많다는 경험을 공유했다.
• Semantic Function / Pragmatic Function 개념이 Google Testing Blog에서 소개한 'Functional Core, Imperative Shell(FCIS)' 패턴과 거의 같다는 분석이 나왔다. FCIS의 핵심 인사이트는 복잡한 로직을 functional core에 격리하면 의존성이 줄어 테스트 스위트가 빠르고 간결해진다는 것이며, 이 글의 분류 체계와 맥락이 일치한다는 의견이었다.
• '코드 자체가 자기 설명을 해야 한다(self-documenting)'는 원칙에 반론도 있었다. 'why(왜 이렇게 했는지)'는 코드로 표현할 수 없고, 주석 없는 self-documenting 코드는 게으른 개발자의 변명으로 쓰이는 경우가 많다는 의견이었다. 특히 규모가 커지면 self-documenting만으로는 한계가 있다고 지적했다.
• 코드베이스가 깔끔할수록 AI 에이전트 성능이 좋아진다는 실용적 인사이트가 주목받았다. 한 개발자는 'AI 에이전트는 한 태스크만 하고 떠나는 신규 개발자와 같다. 컨벤션도, 히스토리도, 맥락도 모른다. 에이전트가 볼 수 있는 건 코드뿐이고, 코드 품질이 곧 프롬프트다'라고 표현했다. 지저분한 레포에 던지면 매번 새 패턴을 만들어낸다는 경험도 공유됐다.
• 속도 문제에 대해 '의도성은 리뷰 후가 아니라 프롬프트 전에 가져야 한다'는 날카로운 지적이 있었다. AI가 코드를 추가하는 속도가 이해 속도를 앞지르는 게 진짜 위험이라는 데 여러 개발자가 공감했으며, 일부는 AI가 제안하더라도 직접 손으로 코드를 작성하는 방식으로만 사용한다는 강경한 입장도 있었다.

How to Apply

• AI 에이전트를 쓰기 전에 `npx skills add theswerd/aicode`로 이 가이드를 에이전트 스킬로 추가해두면, 에이전트가 코드 생성 시 Semantic/Pragmatic Function 원칙과 타입 안전 모델 설계를 따르도록 사전에 제약을 걸 수 있다.
• AI가 생성한 코드를 리뷰할 때 옵셔널 필드(`?`, `Optional`, `nullable`)가 새로 추가된 곳을 먼저 찾아라. 옵셔널이 정말 필요한지, 아니면 설계를 다시 해서 제거할 수 있는지 검토하는 것만으로도 코드베이스 품질 저하를 조기에 막을 수 있다.
• 복잡한 로직이 하나의 큰 함수에 뭉쳐 있을 때, AI에게 '이 함수를 각각 입력만 받고 출력만 돌려주는 self-describing semantic function들의 체인으로 분해해달라'고 요청하면 가독성과 테스트 커버리지를 동시에 높일 수 있다.
• 같은 구조의 값(`string`, `number`)이 여러 도메인 개념을 표현할 때 TypeScript라면 Brand Type(Branded Type)을 도입해 `type DocumentId = string & { __brand: 'DocumentId' }` 식으로 타입 수준에서 구분하면, AI가 잘못된 타입을 조용히 통과시키는 실수를 컴파일 단계에서 잡을 수 있다.

Code Example

// Brand Type 예시 (TypeScript)
type DocumentId = string & { readonly __brand: 'DocumentId' };
type MessagePointerId = string & { readonly __brand: 'MessagePointerId' };

function getDocument(id: DocumentId) { /* ... */ }

const msgId = 'abc123' as MessagePointerId;
// getDocument(msgId); // ❌ 컴파일 에러: 잘못된 타입 사용 방지

// Semantic Function 예시
function retryWithExponentialBackoff<T>(
  fn: () => Promise<T>,
  maxRetries: number,
  baseDelayMs: number
): Promise<T> {
  // 입력만 받고, 출력만 돌려주고, 사이드 이펙트 없음
}

// npx로 AI 에이전트에 스킬 추가
// npx skills add theswerd/aicode

Terminology

관련 논문

• OpenKnowledge – Obsidian/Notion의 오픈소스 AI-first 대안

  Git 기반 동기화와 Claude/Codex/Cursor 연동을 내장한 로컬 우선 마크다운 에디터로, AI 에이전트의 두 번째 뇌(LLM Wiki)로 활용할 수 있는 오픈소스 도구다.

• Unfireable Safety Kernel: AI 에이전트를 위한 Execution-Time AI Alignment

  AI 에이전트가 자신의 안전장치를 우회할 수 없도록, 에이전트 프로세스 바깥에 수학적으로 증명된 강제 통제 게이트를 배치하는 아키텍처

• RubyLLM: 주요 AI 프로바이더를 모두 지원하는 Ruby 프레임워크

  OpenAI, Claude, Gemini 등 주요 AI 프로바이더를 단일 인터페이스로 통합한 Ruby 프레임워크로, Rails 통합과 에이전트 기능까지 지원해 Ruby 개발자가 AI 기능을 빠르게 붙일 수 있다.

• Qwen-AgentWorld: 범용 에이전트를 위한 Language World Model

  Alibaba Qwen 팀이 AI 에이전트가 행동 결과를 미리 시뮬레이션할 수 있는 'Language World Model'을 공개했다. 에이전트 훈련과 실행 경로 검증에 새로운 패러다임을 제시하는 연구다.

• SHERLOC: Code Repair Agent를 위한 구조화된 Diagnostic Localization 프레임워크

  버그 위치만 알려주는 게 아니라 '왜, 어떻게 고쳐야 하는지'까지 진단 리포트를 생성해서 코드 수정 에이전트의 성능을 높이는 training-free 프레임워크

• peerd – 브라우저에서 완전히 실행되는 AI Agent Harness

  백엔드 서버 없이 Chrome/Firefox 확장 프로그램으로만 동작하는 AI 에이전트 실행 환경으로, 브라우저 탭을 직접 조작하고 WASM Linux VM까지 구동할 수 있어 프라이버시와 보안을 동시에 챙길 수 있다.

Related Resources

• Be intentional about how AI changes your codebase (원문)
• Google Testing Blog: Simplify Your Code with Functional Core, Imperative Shell