와일드 코딩

File-based Planning Workflow 파트 2: 실행 기록으로 코딩 에이전트의 맥락을 유지하기

아샬

File-based Planning Workflow 시리즈:

  1. 파트 1: 스펙과 계획으로 코딩 에이전트와 협업하기
  2. 파트 2: 실행 기록으로 코딩 에이전트의 맥락을 유지하기

문제: 구현 단계에서 맥락이 사라집니다

파트 1에서 spec.md와 plan.md를 만들었습니다.

여기까지는 좋습니다.
하지만 실제 구현에 들어가면 금방 다른 문제가 생깁니다.

  • 어떤 작업을 먼저 했는지
  • 왜 이 방식을 선택했는지
  • 어떤 실수를 했고 어떻게 고쳤는지
  • 다음 세션에서 어디서부터 다시 시작해야 하는지

이 맥락이 기록되지 않으면, 코딩 에이전트는 같은 실수를 반복합니다.

해법: 실행 단계의 기억을 파일로 남깁니다

맥락이 사라지는 건 AI의 한계가 아닙니다. 기록하지 않았기 때문입니다. 1

spec.md와 plan.md가 “무엇을”과 “어떻게”를 정했다면,
실행 단계에서는 “왜 이렇게 했는지”를 남겨야 합니다.

FBPW는 파트 1의 spec.md, plan.md에 이어 세 개의 파일을 더 운영합니다.

specs/login-feature/
├── spec.md         # 무엇을 만들지 (파트 1)
├── plan.md         # 어떻게 만들지 (파트 1)
├── tasks.md        # 지금 무엇을 할지
├── findings.md     # 무엇을 배웠고 결정했는지
└── progress.md     # 어디까지 했는지

작업 단위, 결정 근거, 세션 맥락을 분리해서 기록합니다.

1단계: tasks.md - 실행 가능한 작업 목록

plan.md가 전체 설계도라면, tasks.md는 지금 당장 실행할 작업 목록입니다.

큰 구현을 작고 검증 가능한 단위로 쪼갭니다. 예를 들어 로그인 기능 구현 중이라면 이런 모습입니다.

# Tasks: 사용자 로그인

## Goal

로그인 API 구현 및 실패 정책 적용

## Current Phase

🔄 Phase 3: Implementation

## Phases

### Phase 1: Requirements & Discovery ✅

- [x] 요구사항 정의
- [x] 스펙 문서 작성 (spec.md)

### Phase 2: Planning & Structure ✅

- [x] 구현 계획 작성 (plan.md)
- [x] 기존 인증 코드 분석

### Phase 3: Implementation 🔄

- [x] Step 1: UI Layer - `POST /api/session` 엔드포인트 테스트 작성
- [x] Step 1: UI Layer - `SessionController` 구현
- [x] Step 1: UI Layer - 요청/응답 구조 리팩터링
- [ ] Step 2: Application Layer - 로그인 시나리오 테스트 작성
- [ ] Step 2: Application Layer - `LoginService` 구현
- [ ] Step 2: Application Layer - `LoginService` 리팩터링
- [ ] Step 3: Domain Layer - 패스워드 해싱/검증 테스트 작성
- [ ] Step 3: Domain Layer - `User` 모델 구현
- [ ] Step 3: Domain Layer - 리팩터링

### Phase 4: Testing ⏸️

- [ ] 전체 빌드 확인
- [ ] 전체 테스트 통과 확인

이 구조가 주는 효과는 명확합니다.

  1. 현재 어느 단계인지 한눈에 파악됩니다.
  2. 에이전트가 다음에 무엇을 할지 스스로 판단합니다.
  3. 세션이 바뀌어도 작업 흐름이 끊기지 않습니다.

2단계: findings.md - 발견, 결정, 실수 기록

코딩 에이전트가 가장 자주 놓치는 것은 “왜 이렇게 했는가”입니다.

findings.md에는 작업하면서 발견한 것을 계속 남깁니다. 조사 결과, 기술 결정, 실수와 교정은 물론, 작은 배움이라도 그때그때 기록합니다.

# Findings & Decisions

## Research Findings

### 인증 토큰 전달 방식

- 기존 코드베이스는 Authorization 헤더를 사용한다.
- 쿠키 기반으로 바꾸면 CORS 정책 수정이 필요하다.

## Technical Decisions

| 결정 | 이유 | 트레이드오프 |
| ---- | ---- | ----------- |
| 헤더 기반 JWT 유지 | 기존 API와 호환 | XSS 방어 고려 필요 |

## Issues Encountered

### 1. 로그인 실패 메시지 불일치

**문제**: 테스트는 “이메일 또는 패스워드”를 기대했지만
구현은 “로그인 실패”를 반환했다.

**원인**: `ErrorCode` 상수 재사용으로 메시지가 덮어씌워졌다.

**해결**: 로그인 전용 에러 코드를 추가하고
실패 시나리오 테스트를 분리했다.

**결과**: 인수 테스트와 API 응답이 일치한다.

## Learnings

### `PasswordEncoder`는 Bean으로 등록해야 한다 (2026-02-22)

Spring Security의 `PasswordEncoder`는 Bean으로 등록해야
`LoginService`에서 주입받을 수 있다.

### `@ResponseStatus`로 201 반환 (2026-02-22)

`@ResponseStatus(HttpStatus.CREATED)`를 컨트롤러에 붙이면
별도 `ResponseEntity` 없이 201을 반환할 수 있다.

이 파일은 회고 문서가 아닙니다.
작업 중에 바로 업데이트하는 운영 문서입니다.

3단계: progress.md - 세션 재시작을 위한 로그

긴 작업은 여러 세션에 걸칩니다.
다음 세션에서 바로 이어받으려면 멈춘 지점이 명확해야 합니다.

progress.md는 “무엇을 했는지”보다 “어디서 멈췄는지”에 집중합니다.

# Progress Log

## Session 2026-02-22

### Phase 1: Requirements & Discovery ✅

**작업 내역**:

1. 로그인 요구사항 정리
2. `spec.md` 초안 작성 및 리뷰

**생성/수정 파일**:

- `specs/login-feature/spec.md` (새로 생성)

### Phase 2: Planning & Structure ✅

**작업 내역**:

1. Outside-In TDD 구현 계획 작성
2. 기존 `SecurityConfig` 분석

**생성/수정 파일**:

- `specs/login-feature/plan.md` (새로 생성)

### Phase 3: Implementation 🔄

**작업 내역**:

1. Step 1: `SessionControllerTest` 작성
2. Step 1: `SessionController` 구현
3. Step 1: 요청/응답 구조 리팩터링

**생성/수정 파일**:

- `src/.../SessionControllerTest.kt` (새로 생성)
- `src/.../SessionController.kt` (새로 생성)
- `src/.../LoginRequestDto.kt` (새로 생성)

### Phase 4: Testing ⏸️

아직 시작 안 함

## Error Log

| Timestamp  | Error          | Attempt | Resolution     |
| ---------- | -------------- | ------- | -------------- |
| 2026-02-22 | 실패 메시지 불일치 | 1    | 전용 에러 코드 추가 |

## 5-Question Reboot Check

| Question               | Answer                |
| ---------------------- | --------------------- |
| 1. 현재 어느 단계인가? | Phase 3 (Step 1 완료) |
| 2. 다음에 할 일은?     | Step 2 테스트 작성    |
| 3. 목표는?             | 로그인 API 구현       |
| 4. 지금까지 배운 것?   | findings.md 참고      |
| 5. 완료한 작업은?      | 위 내용 참고          |

5-Question Reboot Check가 핵심입니다.
새 세션에서 에이전트가 이 다섯 항목만 읽으면 바로 작업을 재개할 수 있습니다.

실전 루프

실제 작업에서는 이 순서를 반복합니다.

  1. tasks.md에서 다음 작업 하나를 선택합니다.
  2. 구현 중 조사와 판단을 findings.md에 즉시 기록합니다.
  3. 각 작업을 마친 뒤 tasks.md 상태를 갱신합니다.
  4. 세션 종료 전에 progress.md에 현재 상태와 다음 액션을 남깁니다.

이 루프를 지키면, 에이전트를 바꿔도 흐름이 유지됩니다.

에이전트에게 지시하는 방법

프롬프트도 달라져야 합니다.
구현을 요청할 때 파일 갱신까지 포함해서 지시합니다.

specs/login-feature 폴더를 참고해서 구현해줘.
각 단계를 마칠 때마다 tasks.md, findings.md, progress.md도 업데이트하고.

폴더 안에 스펙, 계획, 작업 목록이 있으니 에이전트가 스스로 맥락을 파악합니다.
구현을 진행하면서 파일 갱신까지 함께 요청하면, 코드뿐 아니라 다음 세션을 위한 기록도 남습니다. 코드 리뷰나 회고에서 "왜 이렇게 구현했는지"를 바로 확인할 수 있습니다.

정리

파트 1에서 “무엇을”과 “어떻게”를 정했습니다.
파트 2에서는 실행 과정을 기록하는 법을 다뤘습니다.

  1. tasks.md로 작업 단위를 관리합니다.
  2. findings.md로 결정과 실수를 기록합니다.
  3. progress.md로 세션 맥락을 이어갑니다.

AI에게 가장 어려운 것은 맥락 유지입니다.
파일로 기록하면, 그 약점이 문제가 되지 않습니다.

FBPW 템플릿: https://github.com/ahastudio/file-based-planning-workflow

간단한 예제: 캘린더 예제

Footnotes

  1. 기록이 남는 방식으로 AI와 함께 일하기 https://dal-lab.com/2026/01/23/file-based-planning-workflow/ ↩

다른 글 더 보기