내가 남기고 싶었던 것은 세션 로그가 아니라 Issue / Plan / Progress였다

서론

본래 저는 AI와의 개발 세션 로그(Session Log)를 공개해 왔습니다.

왜 세션 로그를 공개했는지 생각해보면, 아마 제 안에 약간의 불안함이 있었기 때문이라고 생각합니다.

AI에게 개발 작업을 맡기면, 상당히 빠른 속도로 코드를 읽고, 수정하고, 테스트하고, 정리해 줍니다.

그것은 편리합니다.

하지만 한편으로는,

• AI가 무엇을 보고 판단했는지
• 어떤 이유로 그 수정을 선택했는지
• 어디까지 확인했는지
• 무엇을 확인하지 않았는지
• 인간은 어디를 보면 되는지

를 나중에 알 수 없으면 조금 무섭다는 느낌도 들었습니다.

AI가 제대로 작업하고 있는 것처럼 보여도, 그 중간 과정이 보이지 않으면 어딘가 블랙박스(Black Box)처럼 느껴집니다.

그래서 저는 AI와의 세션 로그를 공개했던 것이라고 생각합니다.

완성된 코드뿐만 아니라, AI가 어떻게 생각하고 어떻게 작업했는지도 남겨두고 싶었습니다.

그래야 나중에 다시 볼 수 있고, 다른 사람에게도 설명하기 쉽기 때문입니다.

그런 감각이 있었습니다.

하지만 한동안 AI를 사용하다 보니, 생각이 조금씩 바뀌기 시작했습니다.

최근의 AI는 우리가 일일이 전부 추적하지 않아도 상당히 확실하게 작업을 수행하는 장면이 늘어나고 있습니다.

물론 확인은 필요합니다.

하지만 AI와의 대화를 통째로 남기지 않으면 불안할 정도는 아닐지도 모른다는 생각이 들었습니다.

오히려 나중에 다시 보기 위해 필요한 것은 세션 로그 전문이 아니라,

• 무엇을 고치고 싶었는지
• 어떤 계획으로 진행했는지
• 어디까지 작업했는지
• 무엇을 확인했는지
• 무엇이 남아있는지

를 정리한 기록이 아닐까 하는 생각이 들었습니다.

그 계기 중 하나는 AI가 즉시 코드를 고치러 가는 것이었습니다.

"이 기능은 어떻게 되어 있나요?"

"이 화면의 동작을 조사해 주세요."

"이 에러의 원인을 파악하고 싶습니다."

라고 전달하면, AI는 즉시 관련 파일을 찾아 코드를 변경하려고 합니다.

물론 그것은 AI 개발의 강점입니다.

작은 수정이나 시제품(Prototype)이라면 그 속도감은 상당히 편리합니다.

다만, 업무로서 남기고 싶은 작업의 경우에는 이야기가 조금 달라집니다.

갑자기 코드가 변경되면, 무엇을 보고 어떻게 판단하며 어디까지 확인할 생각인지 보이지 않는 채로 진행되어 버립니다.

그래서 저는 AI에게 처음에 이렇게 말하게 되었습니다.

아직 코드를 변경하지 마세요.
먼저 코드를 확인하고 구현 계획(Implementation Plan)을 작성해 주세요.
그 후에 그 내용에 따라 작업에 들어가 주길 바랍니다.

이것이 현재 운용의 계기입니다.

처음부터 "Issue / Plan / Progress라는 운용 방식으로 하고 싶다"라고 명확하게 설계했던 것은 아닙니다.

AI가 즉시 코드 수정을 진행하려는 것을 일단 멈추고, 먼저 작업을 정리하게 한다.

그를 위해 Issue를 쓰게 한다.

Plan을 쓰게 한다.

작업을 하면 Progress를 남기게 한다.

그렇게 하다 보니 자연스럽게 issue.md / plan.md / progress.md를 태스크(Task)별로 남기는 형태가 되었습니다.

그리고 직접 해보며 깨달았습니다.

제가 남기고 싶었던 것은 AI와의 대화 그 자체가 아니었을지도 모릅니다.

제가 남기고 싶었던 것은 AI에게 무엇을 생각하게 하고, 어떤 계획을 세우게 하며, 어디까지 작업으로서 진행했는가 였던 것 같습니다.

즉, 남기고 싶었던 것은 세션 로그가 아니라,

• Issue
• Plan
• Progress

와 같은 작업의 구조였던 것이라고 생각합니다.

이 기사에서는 그 형태로서, issue.md / plan.md / progress.md를 태스크별로 남기는 운용 방식을 정리해 보겠습니다.

계획을 먼저 쓰게 하면 AI의 움직임이 바뀐다

이 "아직 코드를 변경하지 마세요"라는 말은 단순히 AI를 멈추기 위한 말이 아닙니다.

AI의 역할을 일단 구현자에서 작업 정리 역할로 전환하기 위한 말이라고 생각합니다.

먼저 Issue와 Plan을 만들게 하면 인간이 확인할 수 있는 포인트가 생깁니다.

• 목표가 맞는지
• 성공 조건이 충분한지
• 건드리려는 범위가 너무 넓지는 않은지
• 건드리지 말아야 할 곳이 섞여 있지는 않은지
• 확인 방법이 현실적인지

이 부분을 확인한 뒤 구현에 들어가면, AI의 속도는 유지하면서 작업의 입구만은 인간이 쥐고 있는 듯한 느낌을 줍니다.

솔직히 조금 놀랐습니다.

제가 처음부터 "Issue / Plan / Progress라는 운용 방식으로 하고 싶다"라고 명확하게 설계했던 것은 아닙니다.

오히려 AI가 곧바로 코드 수정으로 넘어가려는 것을 일단 멈추고, 제대로 계획을 세운 뒤에 작업을 수행하도록 하려다 보니 자연스럽게 이 형태에 가까워졌습니다.

이미 하고 계신 분들은 이미 하고 있는 방법일 것입니다.

다만 저에게는, AI에게 "갑자기 고치지 말고, 우선 작업을 정리해줘"라고 부탁하는 것만으로도 작업 단위가 이 정도로 명확하게 보이게 된 것이 꽤 큰 깨달음이었습니다.

실제 파일 구성

제 경우에는 작업 단위별로 디렉터리 (Directory)를 나누는 방식이 잘 맞았습니다.

처음에는 하나의 마크다운 (Markdown) 파일에 모아서 작성해도 좋다고 생각합니다.

다만 실제로 AI에게 작업을 시켜보니, 사전의 Issue, Plan, 작업 중인 Progress를 나누는 편이 가시성이 좋아졌습니다.

예를 들어, 다음과 같은 구성입니다.

tasks/
2026-06-11-user-search-fix/
issue.md
...

디렉터리 이름은 날짜와 작업 내용으로 해도 좋습니다.

tasks/
2026-06-11-user-search-fix/
issue.md
...

GitHub Issue 등과 연결한다면 티켓 번호도 좋을 것 같습니다.

tasks/
#12-user-search-fix/
issue.md
...

날짜와 티켓 번호를 모두 넣어도 좋다고 생각합니다.

tasks/
2026-06-11-#12-user-search-fix/
issue.md
...

이렇게 구성하면 각각의 파일의 역할이 명확해집니다.

파일	역할
issue.md	무엇을 고치고 싶은지, 목표, 현황, 성공 조건, 제약 사항을 작성
plan.md	어떻게 조사하고, 어떻게 구현하며, 어떻게 확인할지를 작성
progress01.md	AI가 작업 중에 수행한 조사·변경·확인을 기록
progress02.md	추가 수정이나 다음 작업 단위의 기록을 작성
progress03.md	추가적인 수정이나 확인 결과를 작성

제 생각에는, issue.md와 plan.md는 사전에 AI에게 작성을 요청하는 파일입니다.

반면, progress01.md 이후는 AI가 실제로 작업을 하면서 남기는 기록입니다.

즉, 세션 로그 (Session Log)를 통째로 남기는 것이 아니라, 작업별 진행 메모로서 남깁니다.

issue.md に書くこと

issue.md는 작업의 입구입니다.

여기에는 갑자기 구현 방법을 쓰는 것이 아니라, 우선 "무엇을 해결하고 싶은가"를 씁니다.

예를 들어, 다음과 같은 내용입니다.

issue.md の例を見る

# 사용자 목록 화면에 이메일 주소 검색 추가
## 목표
사용자 목록 화면에서 이름뿐만 아니라 이메일 주소로도 검색할 수 있도록 한다.
...

issue.md를 만드는 장점은 AI에게 작업의 목적을 명확하게 전달할 수 있다는 것입니다.

AI에게 갑자기 "이 기능을 추가해줘"라고 부탁하면, 의도하지 않은 범위까지 변경되는 경우가 있습니다.

먼저 Issue로서,

• 목표
• 성공 조건
• 제약 사항
• 확인 방법

을 쓰게 해두면 작업의 어긋남이 줄어듭니다.

plan.md に書くこと

plan.md는 구현 전의 작업 계획입니다.

여기서는 AI에게 갑자기 코드를 변경하게 하는 것이 아니라, 우선 조사와 구현 방침을 정리하게 합니다.

예를 들어, 다음과 같은 내용입니다.

plan.md の例を見る

# 작업 계획
## 조사 절차
1. 사용자 목록 화면의 검색 로직을 확인한다
...

이 단계에서도 아직 구현은 시키지 않습니다.

우선 Plan을 사람이 읽습니다.

여기서,

"그 파일은 틀렸어"

"그 확인은 부족해"

"그 부분은 건드리지 않았으면 좋겠어"

라는 판단을 개입시킵니다.

AI에게 맡기기 전에 사람이 작업 범위를 확인한다. 이것만으로도 안심되는 정도가 크게 달라집니다.

progress.md に書くこと

progress.md는 AI가 실제로 작업을 하면서 남기는 기록입니다.

여기에는 대화 로그가 아니라 작업 결과를 쓰게 합니다.

예를 들어, 다음과 같은 내용입니다.

progress.md の例を見る

# progress01
## 실시한 작업
- 사용자 목록 화면의 검색 로직을 확인했다
...

이것이 있으면 다음 세션에서 인수인계하기 쉬워집니다.

세션 로그를 전부 읽지 않아도, progress01.md를 보면,

• 무엇을 했는지
• 어떤 파일을 변경했는지
• 무엇을 확인했는지
• 무엇이 미확인 상태인지

를 알 수 있습니다.

이는 스스로 다시 확인할 때도 편리하며, 누군가에게 설명할 때도 편리합니다.

태스크별로 브랜치 만들기

이 운용 방식은 Git의 브랜치 (Branch)와도 궁합이 좋습니다.

예를 들어, 하나의 수정 단위에 대해 하나의 태스크 디렉토리 (Task Directory)와 하나의 브랜치를 만듭니다.

task: tasks/2026-06-11-user-search-fix/
branch: feature/user-search-fix

티켓 번호를 사용한다면 다음과 같습니다.

task: tasks/#12-user-search-fix/
branch: feature/#12-user-search-fix

실제 운용 이미지는 다음과 같습니다.

1. 수정하고 싶은 내용을 AI에게 전달한다
2. AI에게 tasks/ 하위에 issue.md와 plan.md를 만들게 한다
3. 사람이 issue.md와 plan.md를 확인한다
...

이렇게 하면 작업 단위가 상당히 명확해집니다.

Issue
↓
Plan
...

AI에게 작업을 시키면 아무래도 대화의 흐름에 따라 진행되기 쉽습니다.

하지만 브랜치와 태스크 디렉토리를 대응시켜 두면, 작업 단위가 무너지기 어려워집니다.

AI에게 보내는 첫 번째 요청 예시

처음에 AI에게 부탁할 때는 다음과 같이 하고 있습니다.

처음에 AI에게 전달하는 프롬프트 (Prompt) 예시

다음 수정을 하고 싶습니다.
【하고 싶은 것】
사용자 목록 화면에서 이메일 주소로도 검색할 수 있게 하고 싶습니다.
...

이 단계에서는 AI에게 구현을 시키지 않습니다.

먼저 issue.md와 plan.md를 만들게 하여 사람이 확인합니다.

문제가 없다면, 다음에 이렇게 요청합니다.

구현을 시작하게 할 때의 프롬프트 (Prompt) 예시

tasks/2026-06-11-user-search-fix/plan.md 를 읽어주세요.
이 Plan에 따라 작업해 주세요.
변경은 최소한으로 해주세요.
...

이렇게 하면 AI와의 대화가 아니라, 태스크 디렉토리가 작업의 중심이 됩니다.

다음 세션이 되어도 다음과 같이 요청할 수 있습니다.

다음 세션에서 인수인계할 때의 프롬프트 (Prompt) 예시

tasks/2026-06-11-user-search-fix/ 를 읽어주세요.
issue.md, plan.md, progress01.md 를 확인하여,
현재 작업 상황과 다음에 해야 할 일을 정리해 주세요.
...

이렇게 하면 세션을 넘어가더라도 작업을 재개하기 쉬워집니다.

바이브 코딩 (Vibe Coding)을 부정하지는 않는다

여기서 말하고 싶은 것은 바이브 코딩이 나쁘다는 이야기가 아닙니다.

오히려 바이브 코딩이 적합한 작업은 꽤 많습니다.

예를 들어,

• 시험 삼아 만들기
• 분위기 파악하기
• UI를 대략적인 형태로 잡기
• 작은 도구를 기세로 만들기
• 프로토타입 (Prototype) 만들기
• 아이디어를 움직이는 것으로 만들기

이런 작업은 AI와 대화하며 진행하는 것이 더 빠를 때가 있습니다.

처음부터 issue.md나 plan.md를 만들려고 하면 조금 무겁게 느껴질 수도 있습니다.

특히 아직 정답을 모르는 단계에서는 대화하며 만들고, 만져보고, 고쳐 나가는 편이 자연스럽습니다.

반면, 업무로서 남기고 싶은 작업은 별개입니다.

예를 들어,

• 나중에 설명이 필요한 수정
• 영향 범위가 있는 변경
• 누군가에게 인수인계할 가능성이 있는 작업
• 리뷰나 판단 근거를 남기고 싶은 작업
• 운영 환경 (Production)에 반영될 가능성이 있는 변경
• 실패했을 때 원인을 추적하고 싶은 작업

이런 것들은 대화의 기세만으로 진행하기보다, 먼저 issue.md와 plan.md를 만들어 두는 것이 맞다는 느낌이 듭니다.

제 개인적으로는 앞으로 이 두 가지를 구분해서 사용하는 형태가 될 것 같습니다.

작업의 종류	적합한 진행 방식
시제품 제작, UI 확인, 작은 도구	AI와 대화하며 진행
...

가볍게 만드는 것은 AI와 대화하며 진행한다.

업무로서 남기고 싶은 것은 AI에게 계획을 세우게 하여 작업 디렉토리에 남긴다.

이렇게 나누니 최근 느끼던 답답함이 조금 정리된 기분이 듭니다.

세션 로그가 아니라, 작업 디렉토리를 남긴다

이 구성을 해두면 세션 로그를 통째로 남기지 않아도 작업 경위를 쉽게 추적할 수 있습니다.

	지금까지	앞으로
	세션 로그를 저장한다	태스크 디렉토리를 남긴다
	대화를 다시 읽는다	issue.md / plan.md / progress.md를 읽는다
	AI가 무엇을 했는지 대화에서 찾는다	progress에 변경 내용을 남긴다
	다음 세션에서 긴 로그를 전달한다	태스크 디렉토리를 읽게 한다
	작업 단위가 모호하다	태스크와 브랜치(Branch)가 대응한다
	...

제가 하고 싶었던 것은 AI와의 대화를 남기는 것이 아니라, AI에게 맡긴 작업의 단위(Unit)를 남기는 것이었다고 생각합니다.

그런 의미에서 태스크마다 디렉토리를 나누고, issue.md / plan.md / progress.md를 분리하여 남기는 방식은 상당히 잘 맞아떨어집니다.

여기까지 쓰니 마치 새로운 AI 개발 운영 방식처럼 보일 수도 있습니다.

하지만 잘 생각해보면, 이것은 평소 업무에서 하고 있는 일과 매우 유사하다고 생각합니다.

사람에게 작업을 부탁할 때도 갑자기 "적당히 잘 고쳐놔 줘"라고만 하면, 잘 풀릴 때도 있지만 어긋날 때도 있습니다.

업무로서 부탁한다면 다음과 같은 내용을 전달합니다.

• 무엇을 하고 싶은지
• 어디까지가 범위인지
• 무엇을 성공으로 정의할 것인지
• 무엇을 건드리지 않았으면 하는지
• 어떻게 확인할 것인지

그리고 진척 상황을 묻거나, 결과물을 확인하거나, 필요하다면 방침을 수정합니다.

즉, AI에게 부탁하는 것이나 사람에게 부탁하는 것이나, 부탁하는 방식의 기본은 의외로 비슷할지도 모릅니다.

바이브 코딩(Vibe Coding)은 어떤 의미에서는 "이것 좀 적당히 잘 만들어봐"라고 크게 뭉뚱그려 부탁하는 감각에 가깝습니다.

그것 나름대로 빠르기도 하고, 적합한 상황도 있습니다.

반면, issue.md / plan.md / progress.md로 나누어 부탁하는 방식은 조금 더 업무에 가까운 부탁 방식입니다.

먼저 목적을 맞춘다.
계획을 확인한다.
작업한 내용을 남긴다.
확인한 것과 확인하지 못한 것을 구분한다.

이것은 AI이기 때문에 특별히 필요해진 것이라기보다, 사람에게 일을 부탁할 때도 평범하게 하고 있는 일입니다.

결국 한 바퀴 돌아 다시 그 지점으로 돌아온 느낌이 듭니다.

AI가 대단해졌기 때문에 인간의 업무 방식이 전부 바뀔 것이라고 생각했습니다.

하지만 실제로는 AI가 빠르게 움직일 수 있게 되었기에, 처음에 무엇을 부탁할 것인지, 어떻게 진행할 것인지, 어디까지 확인할 것인지를 정리하는 것의 의미가 더 커진 것이라고 생각합니다.

아마 이런 점을 이미 깨닫고 실천하고 있는 분들도 많을 것입니다.

다만 제 안에서는 세션 로그를 남기는 것에서 시작하여, Issue / Plan / Progress로 나누어 남기는 형태로 정착되었고, 그제야 비로소 "어라, 이거 평범하게 업무를 부탁할 때와 똑같네"라고 깨닫게 된 느낌이었습니다.

그 깨달음이 최근의 저에게는 꽤 흥미로웠습니다.

Discussion