의도와 결정을 잇는 개발 워크플로우 | Agent Workflow

Overview

AI는 이미 충분히 일을 잘합니다. 결과가 어긋나는 주된 이유는 사람의 의도와 제약, 기존 결정이 AI에게 충분히 드러나지 않기 때문입니다.

이번 Chapter에서는 Part 2에서 배운 도구를 에이전트 개발 워크플로우로 연결합니다. URL을 Markdown으로 바꾸는 서비스 Feedme를 직접 클론하며 요구사항부터 구현과 검토, 배포까지 하나의 흐름으로 경험합니다.

학습 목표

• 사람의 의도와 기존 결정을 AI가 판단할 수 있는 작업 전제로 드러내야 하는 이유를 설명합니다.
• 요구사항, 프로젝트 지침, Spec, Git이 작업 전제와 의사결정을 어떻게 이어주는지 구분합니다.
• 강의 프로젝트 템플릿으로 새 저장소를 만들고 로컬에서 실행해 Feedme 개발을 시작할 준비를 마칩니다.

같은 결과를 생각하고 있을까?

사람이 “URL을 Markdown으로 바꾸는 서비스를 만들어줘”라고 말할 때는 이미 머릿속에 원하는 모습이 있습니다. URL을 어디에 입력하고, 변환된 결과를 어떻게 보여주며, 사용자가 그다음에 무엇을 할 수 있어야 하는지까지 생각하고 있습니다.

하지만 AI가 받은 것은 한 문장뿐입니다. 어떤 도구로 본문을 추출할지, 제목과 저자를 보여줄지, 복사와 다운로드가 필요한지 알 수 없습니다. AI는 비어 있는 부분을 합리적으로 채우지만, 그 결과가 사람이 원한 모습과 같다는 보장은 없습니다.

대화에서 차이를 바로잡더라도 결정이 기록되지 않으면 다음 대화는 다시 처음부터 시작합니다. 같은 질문과 이미 버린 선택이 반복되는 이유입니다.

문제는 AI의 능력이 아니라, 사람이 원하는 결과와 앞서 내린 결정이 충분히 드러나지 않은 것입니다.

작업 전제 드러내기

요구사항은 원하는 결과와 제약을, 프로젝트 지침은 반복해서 적용할 기준을, 코드와 테스트는 현재 동작과 바꾸면 안 되는 조건을 보여줍니다.

각각의 사용법보다 중요한 것은 이 정보들이 함께 사람의 의도를 AI가 판단할 수 있는 작업 전제로 만든다는 점입니다. 작업 전제가 충분히 드러나면 AI에게 구현 순서를 하나씩 지시하지 않아도 됩니다. AI는 주어진 의도와 제약 안에서 구체적인 방법을 스스로 선택할 수 있습니다.

결정을 대화 밖에 남기기

작업을 시작하면 처음에는 없던 결정이 계속 생깁니다. 어떤 결과를 보여줄지, 무엇을 범위에서 제외할지, 어떤 기준을 통과해야 완료인지가 대화 속에서 구체화됩니다.

예를 들어 URL을 Markdown으로 바꾸는 서비스에 사용자가 프롬프트를 직접 입력하는 기능이 있다고 해보겠습니다. 대화에서 “직접 입력한 프롬프트는 저장하지 않고 한 번만 사용한다”고 결정했습니다.

이 결정이 대화에만 남아 있으면 새로운 대화의 AI는 이를 알 수 없습니다. 사용자 편의를 위해 입력값을 브라우저에 저장하는 기능을 추가하거나, 저장 여부를 다시 질문할 수 있습니다. 합리적인 선택이지만 이미 내린 결정과는 다릅니다.

Spec에 “직접 입력한 프롬프트는 저장하지 않는 1회용 입력이다”라고 남겨두면 새로운 대화도 같은 전제에서 작업을 이어갑니다. 모든 대화를 보존할 필요는 없습니다. 현재 유효한 결정과 그 이유만 남기면 됩니다.

이번 작업의 결정과 완료 기준은 Spec에, 구현 결과와 변경 상태는 Git에 남깁니다. 여러 작업에서 계속 사용할 결정은 프로젝트 지식으로 보존합니다. 그러면 새로운 대화도 처음부터 다시 판단하지 않고 이전 작업을 이어갈 수 있습니다.

이번 Chapter에서 클론할 서비스: Feedme

feedme.wiki는 웹페이지 주소를 입력하면 본문을 Markdown으로 바꾸고, 그 결과를 다른 곳에서 사용할 수 있게 해주는 서비스입니다.

이번 Chapter에서는 Feedme의 핵심 사용자 흐름을 직접 구현합니다.

• 웹페이지 URL을 입력합니다.
• 본문을 Markdown으로 변환합니다.
• 변환된 제목, 저자와 본문을 확인합니다.
• 결과를 복사하거나 Markdown 파일로 내려받습니다.
• 필요한 프롬프트와 함께 ChatGPT 또는 Claude로 보냅니다.

다섯 Lesson에 걸쳐 요구사항을 구체화하고, 구현하고, 결과를 검토합니다. 마지막에는 완성한 Feedme를 배포해 직접 접속할 수 있는 상태까지 만듭니다.

Skill로 이어지는 개발 워크플로우

• discover-opportunity → shape-idea: 만들 문제가 정해지지 않았다면 기회를 찾은 뒤 구체화할 방향을 넘깁니다. 이번에는 Feedme를 클론하기로 정했으므로 shape-idea에서 시작합니다.
• shape-idea ↔ build-prototype: 말만으로 판단하기 어려운 사용자 경험이 남아 있을 때 프로토타입을 직접 확인하고 결정을 Spec에 반영합니다.
• shape-idea → implement: 모든 부분을 함께 완성해야 사용할 수 있다면 Spec에서 바로 구현으로 이어집니다.
• shape-idea → split-into-tasks → implement: 각 부분을 따로 완성해도 사용할 수 있다면 Task로 나눈 뒤 하나씩 구현합니다.
• implement → human-review: 구현과 자동 검증이 끝난 뒤에도 사람의 판단이 필요한 결과가 있을 때만 검토를 요청합니다.
• project-knowledge → compact-decisions: 다음 작업도 알아야 할 결정을 프로젝트 지식으로 남기고, 여러 작업이 쌓이면 중복되거나 오래된 기록을 정리합니다.

add-stack-context와 explain-visually는 특정 순서에 묶이지 않습니다. 공식 기술 지침이 필요하거나 문장만으로 구조를 이해하기 어려운 순간에 사용합니다.

implement는 사람과 테스트할 동작과 확인 방법을 먼저 정하고, 그 동작을 자동으로 확인할 수 있을 때 TDD를 사용합니다. 실패하는 테스트, 최소 구현, 리팩터링을 반복하고, 모든 결과를 구현한 뒤에는 전체 변경을 Spec과 완료 기준에 대조하는 자동 코드 리뷰까지 거칩니다. 코드를 바꾸기 전에 AI가 어떤 파일을 어떻게 수정할지 직접 확인하고 싶을 때 Plan Mode를 사용합니다.

이 흐름을 지나며 대화의 핵심 상태는 파일로 남습니다. 처음 받은 요구사항은 출발점으로 보존하고, shape-idea에서 확정한 동작과 완료 기준은 Spec에 기록합니다. Task로 나눴다면 Task 문서가 진행 상태를 이어받고, implement는 코드와 테스트, Git 기록을 남깁니다. 여러 작업에서 재사용할 용어와 결정만 프로젝트 지식으로 보존합니다.

워크플로우는 정답이 아니라 출발점

저는 Matt Pocock이 제안한 Skill 철학에서 출발해 이 워크플로우를 만들었습니다. 사람의 의도를 충분히 드러내고, 자신이 AI와 일하는 방식을 Skill에 담아 반복해서 사용하는 접근입니다.

이번 Chapter에서는 먼저 이 워크플로우의 한 사이클을 따라 Feedme를 완성합니다. 전체 흐름을 한 번 경험해야 어떤 부분이 도움이 되고, 어떤 부분이 자신의 방식과 맞지 않는지 판단할 수 있습니다.

한 사이클을 마친 뒤에는 그대로 사용할 필요가 없습니다. 마음에 들지 않는 Skill은 빼고, 필요한 Skill은 추가하며, 질문 방식과 검토 기준도 각자의 스타일에 맞게 바꾸면 됩니다.

이 워크플로우는 따라야 할 정답이 아니라, 자신만의 AI 개발 워크플로우를 만들기 위한 출발점입니다.

[미션] 템플릿으로 시작하기

Step 1: 새 GitHub 저장소 만들기

강의 프로젝트 템플릿에 접속합니다. Use this template을 클릭한 뒤 Create a new repository를 선택합니다.

저장소 이름은 feedme-clone으로 입력하고 생성합니다.

Step 2: 로컬에 클론하기

생성한 저장소에서 Code → HTTPS를 선택하고 저장소 주소를 복사합니다.

터미널에서 저장소를 클론하고 프로젝트 폴더로 이동합니다.

git clone <복사한 저장소 주소>
cd feedme-clone

Step 3: 개발 서버 실행하기

의존성을 설치하고 개발 서버를 실행합니다.

bun install
bun dev

터미널에 표시된 주소를 브라우저에서 엽니다. 템플릿의 초기 화면이 나타나면 Feedme를 만들 준비가 끝났습니다.

핵심 포인트 정리

1. 작업 전제의 불일치: 사람의 의도·제약·기존 결정이 충분히 드러나지 않으면 AI는 비어 있는 부분을 추측하고, 결과는 원하는 방향에서 어긋납니다.
2. 대화 밖의 결정: 현재 유효한 결정과 그 이유를 Spec과 프로젝트 지식에 남기면 새로운 대화에서도 같은 판단을 반복하지 않습니다.
3. 워크플로우는 출발점: 먼저 Skill의 전체 흐름을 경험한 뒤, 질문 방식과 검토 기준을 각자의 취향에 맞게 바꿔 사용합니다.

이어서 배울 내용

다음 Lesson에서는 shape-idea Skill과 대화하며 Feedme에서 구현할 사용자 흐름과 범위를 구체화합니다. 머릿속에 있던 의도와 제약을 드러내고, 구현의 기준이 될 Spec으로 남깁니다.