결정 로그

Decision Log

기초 난이도: 기초태그: 결정로그 · 아키텍처결정 · 맥락보존

DEFINITION

정의

프로젝트에서 이미 합의한 기술 선택, 금지한 접근, 보류한 이유, 검증 결과를 시간순으로 남기는 기록이다. AI는 긴 대화가 이어지면 초반의 아키텍처 결정이나 배포 제약을 잊을 수 있으므로, 결정 로그를 컨텍스트에 넣으면 같은 논의를 반복하지 않고 일관된 방향으로 코딩할 수 있다. 좋은 결정 로그는 '무엇을 선택했는가'뿐 아니라 '왜 선택했는가', '언제 다시 검토할 것인가', '어떤 테스트로 확인했는가'를 함께 남긴다. 이는 context rot을 줄이는 실용적 장치다.

참고

ADR처럼 무겁게 시작하지 않아도 작은 변경 이유와 검증 결과를 남기면 AI 인수인계 품질이 올라간다.

ENGLISH

Decision Log

EXAMPLE

결제 기능에서 'DB 스키마 변경은 이번 배포에서 제외, API 응답 호환성 유지, 회귀 테스트 통과 후 다음 PR에서 마이그레이션 검토'라는 결정 로그를 남겨 다음 AI 세션이 같은 위험한 변경을 다시 제안하지 않게 한다. 배포 뒤에는 검증 결과도 같은 로그에 붙인다.

NOTES

ADR처럼 무겁게 시작하지 않아도 작은 변경 이유와 검증 결과를 남기면 AI 인수인계 품질이 올라간다.

REFERENCE

adr.github.io/

이어서 볼 문서

가이드로 이동 용어를 실제 작업 흐름에서 다시 보기

사전 정의를 읽은 뒤 바이브코딩 가이드에서 사용 맥락을 확인합니다.

질문하기 이 용어가 내 작업에서 어떻게 쓰이나요?

궁금한 맥락을 Q&A로 넘겨 구체적인 답변 흐름으로 이어갑니다.

RELATED TERMS

연관 용어

컨텍스트 엔지니어링 CLAUDE.md / AGENTS.md

CLAUDE.md / AGENTS.md

프로젝트 루트 디렉토리에 배치하는 마크다운 파일로, AI 에이전트에게 프로젝트의 아키텍처, 코딩 컨벤션, 빌드·테스트 명령어, 기술 스택, 제약 조건 등을 알려주는 '프로젝트 지도(map)' 역할을 한다. Claude Code에서 /init 명령어로 자동 생성할 수 있으며, AI가 프로젝트를 처음 접할 때 가장 먼저 읽는 파일이다. 잘 작성된 CLAUDE.md는 AI 에이전트의 코드 생성 품질을 극적으로 향상시키며, 반대로 이 파일이 없으면 AI가 프로젝트의 패턴과 규칙을 이해하지 못해 일관성 없는 코드를 생성한다. Mitchell Hashimoto(하네스 엔지니어링 창시자)는 AGENTS.md를 반복적으로 개선하는 것을 하네스 엔지니어링의 핵심 활동으로 제안했다. 구체적 방법론은: AI 에이전트가 실수를 했을 때, 같은 실수를 반복하지 않도록 해당 규칙을 AGENTS.md에 추가하는 것이다. 시간이 지남에 따라 AGENTS.md는 프로젝트의 모든 '암묵적 규칙'이 명시화된 문서로 성장한다. CLAUDE.md는 Claude Code 전용이고, AGENTS.md는 도구 독립적인 범용 이름이며, 기능과 목적은 동일하다.

컨텍스트 엔지니어링 .cursorrules / .windsurfrules

.cursorrules / .windsurfrules

Cursor IDE의 .cursorrules와 Windsurf IDE의 .windsurfrules는 각각의 IDE에서 프로젝트별 AI 행동 규칙을 정의하는 설정 파일이다. CLAUDE.md가 Claude Code 전용 규칙 파일이라면, .cursorrules는 Cursor 전용, .windsurfrules는 Windsurf 전용 규칙 파일이다. 기능과 목적은 동일하지만 각 도구에 맞는 형식과 지시 방식이 다르다. 프로젝트 루트에 배치하면 AI가 자동으로 읽어 모든 코드 생성과 수정에 적용한다. 대표적인 규칙 내용으로는 '항상 TypeScript strict mode 사용', 'async/await만 사용하고 .then() 체이닝 금지', 'any 타입 절대 사용 금지', '모든 컴포넌트는 함수형으로 작성', '에러 처리에는 반드시 try-catch 사용' 등이 있다. 이러한 규칙 파일이 없으면 AI가 프로젝트 내에서 일관되지 않은 코딩 스타일을 사용하게 되므로, 바이브 코딩을 시작할 때 가장 먼저 설정해야 하는 파일 중 하나이다. 커뮤니티에서 공유되는 .cursorrules 템플릿도 많으므로 참고하면 좋다.

컨텍스트 엔지니어링 검색 증강 생성

RAG (Retrieval-Augmented Generation)

외부 데이터 소스에서 관련 정보를 먼저 검색(Retrieval)한 뒤, 이 정보를 LLM의 컨텍스트에 포함시켜(Augmented) 응답을 생성(Generation)하는 기술이다. 2020년 Meta AI의 Patrick Lewis 등이 발표한 논문에서 처음 제안되었으며, AI의 환각(Hallucination) 문제를 해결하는 가장 효과적인 방법 중 하나로 자리잡았다. LLM은 훈련 데이터에 포함되지 않은 정보(사내 코드, 비공개 API 문서, 최신 라이브러리 변경사항 등)를 알 수 없지만, RAG를 통해 관련 문서를 실시간으로 검색하여 컨텍스트에 주입하면 최신·정확한 정보를 기반으로 코드를 생성할 수 있다. 바이브 코딩에서의 활용 예시: AI 코딩 에이전트가 사내 API 문서 데이터베이스를 RAG로 검색하여, 정확한 엔드포인트 URL, 인증 방식, 요청/응답 스키마를 확인한 후 코드를 생성한다. Grounding의 핵심 구현 방식이며, Corrective RAG(검색 결과의 관련성을 평가하여 재검색하는 변형) 등의 발전된 형태도 존재한다.