코딩 에이전트(Coding Agent)를 사용한 개발은 빠릅니다. "인증을 구현하고 싶다"라고 전달하면, 파일 구성 제안부터 구현·테스트까지 순식간에 진행됩니다.

다만, 빠른 만큼 "왜 그런 설계를 했는지", "어떤 트레이드오프(Trade-off)를 선택했는지"가 기록에 남기 어렵습니다. 인간 사이의 리뷰라면 구두로도 보완할 수 있지만, 에이전트와의 상호작용은 세션(Session)을 넘어가면 기본적으로 리셋됩니다. 이전 판단의 근거를 다음 세션에서도 이어받게 하려면, 무언가 명시적인 메커니즘이 필요합니다.

그래서 시도한 것이, 에이전트에게 작업 로그를 자동 생성하게 하는 운용입니다. 운용해 보며 알게 된 점을 정리합니다.

문서는 3개 계층으로 나누어 관리하고 있습니다.

docs/
instructions/ # 세션 작업 로그 (날짜 기반)
20260324.md
...

AGENTS.md는 에이전트가 가장 먼저 읽는 규칙 파일입니다. 이 프로젝트에서는 사용 중인 Next.js 버전의 독자적인 파괴적 변경(Breaking Changes)이 있었기 때문에, 다음과 같은 지시를 넣어두었습니다.

# This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure
may all differ from your training data. Read the relevant guide in
...

"트레이닝 데이터(Training Data)의 지식에 의존하지 말고, 반드시 프로젝트 내의 문서를 읽어라"라는 지시입니다. 코드 생성 전에 실제 사양을 확인하게 함으로써, 오래된 API 패턴으로 구현될 리스크를 줄일 수 있습니다.

여기에 쓰는 것은 "매번 말하지 않아도 되도록 만들고 싶은 지시"뿐입니다. 한 번만 전달하면 충분한 프로젝트 고유의 제약이나 관습을 모아둡니다.

구현·수정이 완료될 때마다, 에이전트에게 docs/instructions/에 로그를 쓰게 합니다.

각 로그는 다음 구성을 기본으로 합니다.

# 작업 로그 YYYY-MM-DD
## 1. <기능명 또는 수정 내용>
### 개요
...

# 작업 로그 2026-04-30
## OAuth 2.1 Authorization Code + PKCE 구현
### 개요
...

"무엇을 구현했는가"보다 "왜 그렇게 했는가", "어디서 막혔는가"를 중심으로 쓰게 하고 있습니다. 구현 내용은 코드나 커밋 히스토리(Commit History)를 통해 읽을 수 있지만, 판단의 배경은 남지 않기 때문입니다.

이 로그가 가장 도움이 되는 것은 여러 세션에 걸친 기능 개발입니다.

예를 들어 패스키(Passkey) 인증 구현에서는, 첫 번째 세션에서 "identifier-first (loginId를 입력한 후 패스키 인증)"라는 설계를 선택했습니다. 그런데 다음 세션에서 "discoverable credentials (OS의 패스키 피커로 직접 인증)"로 변경하게 되었습니다.

변경 경위가 로그에 남아 있다면, 다음 세션에서 "왜 변경했는지"를 다시 설명할 필요가 없습니다.

## discoverable credentials로의 변경 (identifier-first로부터의 이행)
### 변경 배경
identifier-first 방식에서는 사용자가 loginId를 입력하면, 서버가
...

로그에 잘못된 내용이 기록되어 있는 경우, 원래 로그는 고쳐 쓰지 않고, 후속 로그에 정정 섹션을 추가하는 방침을 취하고 있습니다.

로그는 "그 세션 시점에서의 인식"의 기록입니다. 나중에 고쳐 쓰면 "왜 판단이 바뀌었는지"의 경위가 사라지기 때문입니다.

## [정정] OAuth 스코프 설계 수정
### 정정 대상
2026-04-30 로그 「OAuth 2.1 Authorization Code + PKCE 구현」
...

잘못된 로그가 남아 있는 상태에서 새로운 세션을 시작하면, 에이전트는 그 오류를 사실로 읽습니다. 세션 초두에 명시적으로 보정하거나, 정정 내용을 로그 내에 남겨두는 것이 중요합니다.

○○일의 로그에 오류가 있습니다.
services:view의 설계에 대해, 상세 정보 취득에는 services:detail이 필요하도록 변경되었습니다.
○○일의 로그에 정정 내용을 추가해 주세요.

에이전트에게 정정 내용을 추가하게 함으로써, 이후의 세션에서는 올바른 문맥 (Context)을 이어받을 수 있게 됩니다.

테스트에 관해서는 브랜치 (Branch) 단위로 문서를 나누고 있습니다. 파일은 두 종류입니다.

테스트 케이스를 it.todo로 작성한 시점에 에이전트에게 생성하게 합니다. 구현 전의 "무엇을 테스트할 것인가"에 대한 합의로서 사용합니다.

# 테스트 케이스 목록 — feature/add_oauth
## resolve-caller.test.ts (22건)
### resolveFromBearer
...

코드 리뷰 (Code Review) 시에 "이 케이스가 고려되었는가"를 확인하는 데 사용할 수 있습니다. 테스트 코드를 읽지 않아도 사양 (Specification)의 범위를 목록으로 파악할 수 있습니다.

it.todo를 실제 테스트 코드로 변환한 후에 에이전트에게 생성하게 합니다. 구현한 파일, 케이스 수, 테스트 결과를 정리합니다.

# 테스트 코드 구현 기록 — feature/add_oauth
## 구현 파일 목록
| 파일 | 케이스 수 | 종류 |
...

PR (Pull Request) 리뷰 시에 "테스트가 통과되었는지, 어느 계층의 테스트가 몇 건 있는지"를 한눈에 확인할 수 있습니다.

"왜"가 남는다

커밋 메시지 (Commit Message)나 PR 설명은 "무엇을 했는가"에 치우치기 쉽습니다. 작업 로그는 "왜 그런 설계를 했는지", "어떤 선택지를 버렸는지"를 자연스럽게 포함하는 형식이 됩니다. 몇 달 후에 같은 부분을 만질 때, 로그가 있으면 판단을 재현하기 쉽습니다.

삽질 포인트가 자산이 된다

에이전트는 문제에 부딪힌 내용과 대처 방법을 그대로 로그에 써줍니다. 다음 세션에서 같은 문제에 다시 직면했을 때, 로그를 참조하면 같은 조사를 반복하지 않아도 됩니다. 이 기사의 "Next.js 15의 함정 2가지"도 작업 로그를 다시 읽어보며 소재를 찾아냈습니다.

테스트 사양과 구현의 괴리 방지

testcase.md를 구현 전에 출력하게 하는 습관을 통해, "테스트 케이스 설계"와 "코드 구현"이 별개의 페이즈 (Phase)로 분리됩니다. 구현하면서 테스트를 생각하면 놓치기 쉬운 케이스가, 사전에 목록화함으로써 명확해집니다.

로그의 질은 프롬프트 (Prompt)의 질에 의존한다

"작업 로그를 써줘"라고만 전달하면 내용이 부실해집니다. "문제·원인·대처 형식으로, 설계 판단의 이유를 포함해서 써줘"와 같이 형식과 중점을 지시해야 합니다.

업데이트를 잊으면 순식간에 진부해진다

몇 세션 분량의 로그가 빠지면 앞뒤의 연결 고리가 상실됩니다. "구현이 끝나면 로그를 작성한다"를 세션 종료 조건에 포함하는 것이 중요합니다.

코딩 에이전트와의 개발에서 문서를 자동 생성하는 운용을 정리하면 다음과 같습니다.

에이전트가 빠르게 구현해 주는 만큼, "왜 그런 판단을 했는가"는 의식적으로 남겨두지 않으면 사라져 버립니다. 로그 생성을 운용의 일부로 편입함으로써, 속도를 늦추지 않고도 판단의 문맥을 축적할 수 있게 되었습니다.