AI 코딩의 맹점 — Artifacts 없이 에이전트는 기억을 잃는다

AI와 함께 코딩하면서 생긴 버그를 디버깅한다고 치자. "왜 6개월 전에 이렇게 구현했냐"고 AI에게 물으면 돌아오는 답은 하나다. "모르겠다." AI에게는 어제가 없다.

AI 페어 프로그래머의 근본적 한계

인간 개발자는 맥락을 기억한다. 왜 이 데이터베이스를 골랐는지, 왜 그때 저 패턴을 피했는지, 어떤 트레이드오프를 감수했는지를 머릿속에 쌓아간다. 6개월 후 코드를 봐도 "아, 이건 그때 성능 이슈 때문에 이렇게 했지"를 떠올릴 수 있다.

AI는 현재 컨텍스트 윈도우만 본다. 오늘 준 정보로 오늘의 결정을 내릴 수 있지만, 어제의 결정을 내일 설명하는 건 불가능하다.

[💡 잠깐! 이 용어는?] 컨텍스트 윈도우(Context Window): AI 모델이 한 번에 처리할 수 있는 텍스트의 최대 범위. 이 범위를 벗어난 정보는 AI가 "기억"하지 못한다. 긴 대화나 대용량 코드베이스는 윈도우를 초과하면 자동으로 잘려나간다.

비유하면, 매번 새로 고용된 계약직 개발자에게 코드를 맡기는 것과 같다. 실력은 뛰어나지만 히스토리를 전혀 모른다.

이 문제를 해결하는 게 Artifacts다. AI가 기억하지 못하는 것을 문서로 굳혀두는 방식이다.

Artifacts의 네 가지 레이어

[💡 잠깐! 이 용어는?] Artifacts: 소프트웨어 개발 과정에서 생성되거나 사용되는 모든 산출물. 코드 자체뿐 아니라 이슈, PR, 다이어그램, 설계 문서, 목업 등을 포함한다. AI 코딩에서는 AI에게 맥락을 공급하는 핵심 수단이 된다.

PRD (Product Requirements Document)

"무엇을, 왜"를 기록하는 문서다.

## 배경
현재 세션 기반 인증이 모바일 클라이언트에서 불안정함.
 
## 목표
- JWT 기반 인증으로 전환
- Refresh Token 30일, Access Token 15분 만료
 
## 비기능 요구사항
- 기존 세션 사용자 마이그레이션 기간: 30일
- 토큰 무효화는 Redis 블랙리스트 방식
 
## 성공 지표
- 모바일 인증 오류율 < 0.1%

PRD가 있으면 AI는 "왜 이 결정을 내렸는지"의 맥락을 다음 세션에도 이어받을 수 있다. 새 대화에서 PRD를 첨부하면 AI가 프로젝트 배경을 이미 알고 있는 상태에서 작업을 시작한다. 인간 개발자도 PRD 없이 개발하면 기획 의도를 놓치는 경우가 생기는데, AI는 그 문제가 훨씬 더 심각하다.

ADR (Architectural Decision Record)

"왜 이 기술을 골랐는지"를 불변하게 기록하는 문서다. ADR의 핵심은 결정 이후에 수정하지 않는 것이다. 나중에 결정이 바뀌면 새 ADR을 만든다.

## 상태: 승인됨 (2026-01-15)
 
## 맥락
세션 기반 인증은 수평 확장 시 sticky session이 필요.
AWS ALB 환경에서 이 제약이 부담.
 
## 결정
JWT로 전환한다.
 
## 결과
- 장점: 서버리스 무상태 처리 가능
- 단점: 토큰 즉시 무효화 불가 → Redis 블랙리스트로 보완

[💡 잠깐! 이 용어는?] ADR (Architectural Decision Record): 중요한 아키텍처 결정을 기록하는 가벼운 문서. "무엇을 결정했는가"보다 "왜 이 결정을 내렸는가"를 중점적으로 담는다. 결정을 내린 당시의 맥락과 대안을 함께 기록해두면, 나중에 "왜 이랬지?"를 추적할 수 있다.

ADR의 불변성이 핵심이다. 나중에 결정이 바뀌더라도 기존 ADR을 수정하지 않는다. 새 ADR을 만들어서 "이전 결정을 번복한다"는 사실 자체를 기록한다. 비유하면 법원 판결문과 같다. 판결이 바뀌면 원래 판결문을 지우는 게 아니라 새 판결이 나온다. 이 방식 덕분에 "언제, 왜 방향이 바뀌었는지"를 항상 추적할 수 있다.

TDD (Technical Design Document)

"어떻게 구현하는지"를 구체적으로 기술하는 문서다.

## 아키텍처
- Auth Service (NestJS) → Redis (토큰 블랙리스트) → PostgreSQL (사용자)
 
## API 설계
POST /auth/login → { accessToken, refreshToken }
POST /auth/refresh → { accessToken }
POST /auth/logout → 블랙리스트에 토큰 추가
 
## 데이터 설계
users 테이블: id, email, password_hash, created_at
refresh_tokens 테이블: user_id, token_hash, expires_at
 
## 보안
- Access Token: RS256, 15분
- Refresh Token: SHA-256 해시 후 DB 저장
- Rate limiting: /login 5회/분

TDD에서 누락된 항목이 구현 버그의 원인이 된다. 위 예시에서 "Read-through 캐시 로직"이 빠졌다면, 구현 시 Redis와 PostgreSQL 사이에 어떻게 동작해야 하는지 AI가 임의로 추측하게 된다. TDD는 PRD의 "무엇을"과 ADR의 "왜"를 받아서 "어떻게 만드는지"를 구체화하는 문서다. 이 세 문서가 쌓이면 AI에게 줄 수 있는 맥락이 완성된다.

Task List

TDD를 검증 가능한 작업 단위로 쪼갠 목록이다. AI에게 "인증 기능 만들어줘"라고 하면 어디서 어디까지 해야 하는지 범위가 불명확해진다. Task List는 그 범위를 "완료 기준이 붙은 단위 작업들"로 분해한다. 비유하면 이사를 할 때 "집 옮겨"라고 하면 막막하지만, 박스 포장 → 이삿짐센터 예약 → 물건 운반 → 정리라고 쪼개면 오늘 뭘 해야 할지 명확해지는 것과 같다.

## Phase 1: 기반 구축
- [ ] JWT 유틸리티 모듈 생성 (sign, verify, decode)
  - 완료 기준: 단위 테스트 5개 통과
- [ ] Redis 연결 모듈 생성 (블랙리스트 CRUD)
  - 완료 기준: 통합 테스트 통과
 
## Phase 2: 엔드포인트
- [ ] POST /auth/login 구현
  - 완료 기준: E2E 테스트 통과

왜 앞에서 쓰는 게 이득인가

Artifacts를 먼저 만들면 AI가 "맥락 없이 추측"하는 경우가 줄어든다. 비유하면 건축가가 설계도 없이 집을 짓기 시작하는 것과 설계도를 먼저 그리는 것의 차이다. 공사가 시작된 후의 변경은 처음부터 다시 짜는 것보다 훨씬 비싸다.

마무리

AI 코딩은 속도가 빠르다. 하지만 빠른 속도로 맥락 없이 달리다 보면, 며칠 후 아무도 설명 못 하는 코드가 쌓인다. PRD, ADR, TDD는 속도를 늦추는 게 아니라 AI가 달릴 트랙을 깔아주는 작업이다. 문서화가 번거롭게 느껴진다면, AI에게 "이 기능에 대한 PRD를 먼저 작성해줘"라고 시키는 것도 방법이다.

참고:

• 원문: https://humanwhocodes.com/blog/2026/02/artifacts-ai-assisted-programming/