세션에서 배포까지

AI와 만든 결과물은 대화창 안에 머물면 아직 일이 끝난 것이 아닙니다. 이 장은 준비, 개발, 검증, 배포의 네 단계를 한 흐름으로 묶고, 그 바탕이 되는 버전 관리(git), 배포와 되돌리기, 비밀 값 관리, 세션 사이의 인계를 설명합니다.

네 단계 흐름

액티전스 라이브러리는 작업을 준비, 개발, 검증, 배포의 네 단계로 정리합니다. 외울 필요는 없고, 지금 하는 일이 어느 단계인지 알면 필요한 도구가 정해집니다.

각 단계마다 해당 프롬프트 카드가 있고, 단계 사이에 넘기는 정보의 형식도 정해 둘 수 있습니다. 카드 목록은 부록 A에 있습니다.

도구 네 가지의 역할

만든 결과물이 파일로만 남으면 만든 사람만 쓰고 조직에는 남지 않습니다. 파일에서 주소로, 주소에서 데이터로 옮겨 가는 데는 네 가지 도구가 각자의 역할을 맡습니다.

순서는 만든다, 올린다, 주소를 받는다, 데이터를 관리한다입니다. 한 칸씩 올라갑니다. 파일과 주소의 차이는 18장에서 비교합니다. GitHub에 올리면 호스팅 서비스가 변경을 감지해 다시 배포하는 관계는 한 번만 연결해 두면 됩니다. 그 뒤로는 고쳐 달라는 한마디로 주소의 내용이 최신이 됩니다. 연동 방법과 무료 사용 범위는 각 서비스의 공식 문서에서 확인합니다(2026년 11월 기준).

준비

준비 단계의 산출물은 합의서입니다. 9장에서 만든 합의서가 이미 있다면 이번 작업에 맞게 목표와 제약을 갱신하고, 없으면 짧게라도 새로 씁니다. 새 프로젝트라면 어떤 도구를 쓰고 어디에 배포할지도 이 단계에서 정합니다. 이전 작업을 이어받는다면 마지막 인계 문서를 먼저 읽게 합니다(아래 "세션 사이의 인계" 참조).

개발

개발 단계에서는 19장에서 정한 계획의 깊이로 작업합니다. 작업 단위는 작게 쪼갭니다. 한 번에 많이 바꾸면 무엇이 문제를 일으켰는지 찾기 어렵습니다. 작은 단위가 끝날 때마다 커밋을 남기는 습관이 이 단계의 핵심입니다.

검증

검증은 AI의 말이 아니라 실행 결과로 합니다. 테스트와 빌드를 돌리고, 화면이 있는 결과물이라면 실제로 열어 눈으로 봅니다. 핵심 주장 확인과 제약 체크리스트는 19장의 방법을 그대로 씁니다. 검증에서 실패하면 개발 단계로 돌아가는 것이 정상입니다.

배포

배포는 결과물을 다른 사람이 쓸 수 있는 곳에 올리는 일입니다. 올리기 전 점검, 올린 뒤 확인, 문제가 생겼을 때 되돌릴 방법을 한 세트로 준비합니다.

git: 변경의 안전장치

git은 파일의 변경 이력을 기록하는 버전 관리 도구입니다. AI가 파일을 여러 개 수정하는 작업에서는 사실상 필수입니다. 잘못 고쳐졌을 때 이전 상태로 돌아갈 방법이 있어야 마음 놓고 맡길 수 있기 때문입니다. 터미널 명령에 익숙하지 않아도, 아래 네 가지 개념만 알면 됩니다.

• 커밋(commit): 지금 상태를 이름표와 함께 저장하는 것. 게임의 저장 지점과 같습니다.
• 이력(history): 커밋이 쌓인 목록. 언제 무엇이 바뀌었는지 볼 수 있습니다.
• 되돌리기(revert, restore): 이전 커밋의 상태로 돌아가는 것.
• 브랜치(branch): 본 흐름을 건드리지 않고 시험 삼아 작업하는 갈래.

기본 흐름

git status
git add .
git commit -m "문의 응대 안내문 템플릿 추가"
git log --oneline

git status는 지금 바뀐 파일을 보여 주고, git add .는 바뀐 파일을 저장 대상으로 올리고, git commit은 그 상태를 이름표와 함께 저장합니다. git log --oneline은 지금까지의 커밋을 한 줄씩 보여 줍니다. 위 명령은 읽기만 해도 이해할 수 있도록 단순한 것만 골랐습니다.

되돌리기

커밋이 있으면 되돌릴 수 있습니다. 가장 안전한 방법은 문제 커밋의 변경을 거꾸로 적용하는 새 커밋을 만드는 것입니다.

git revert <되돌릴 커밋 번호>

이 방식은 이력을 지우지 않고 되돌린 사실까지 기록으로 남깁니다. 이력을 지우거나 강제로 덮어쓰는 명령(git reset --hard, git push --force 등)은 작업 내용을 잃을 수 있으므로, AI에게 맡길 때도 사람의 확인 없이는 실행하지 않도록 합의서에 적어 둡니다.

AI에게 커밋을 맡길 때의 규칙

• 변경하기 전에 먼저 커밋해서 되돌릴 지점을 만듭니다.
• 커밋 하나에는 한 가지 목적만 담습니다. 기능 추가와 정리를 섞지 않습니다.
• 커밋 메시지는 무엇을 왜 바꿨는지 한 줄로 씁니다.
• 커밋과 원격 저장소로의 업로드(push)는 요청했을 때만 하게 합니다.

git을 더 깊이 배우고 싶다면 무료로 공개된 Pro Git 한국어판을 검색해 보세요. 처음에는 시작하기와 git의 기초 두 장만 읽으면 충분합니다.

비밀 값을 지키는 법

API 키, 비밀번호, 서비스 연결 주소처럼 외부에 알려지면 안 되는 값을 비밀 값이라고 합니다. AI와 함께 코드를 만들 때 가장 흔하고 피해가 큰 실수가 이 값을 코드나 대화에 그대로 적는 것입니다.

원칙

1. 비밀 값은 코드 파일에 쓰지 않고 환경 변수에 둡니다. 로컬에서는 보통 .env 같은 파일에 모읍니다.
2. 그 파일은 git이 추적하지 않도록 .gitignore에 등록합니다. 등록하지 않으면 커밋과 함께 이력에 남습니다.
3. 대화창에 비밀 값을 붙여 넣지 않습니다. 값이 필요하면 "환경 변수 이름만 사용하고 값은 내가 직접 넣겠다"고 지시합니다.
4. 비밀 값이 들어가는 예시 파일은 값을 비운 형태(.env.example)로 만들어 어떤 변수가 필요한지만 알립니다.
5. 배포 서비스에는 그 서비스의 환경 변수 설정 화면에 사람이 직접 입력합니다.

공개 저장소의 위험

공개로 설정된 저장소에 비밀 값이 한 번이라도 올라가면, 나중에 파일에서 지워도 이력에 남습니다. 이미 올라갔다면 파일을 고치는 것으로는 부족하고, 해당 키를 발급처에서 폐기하고 새로 발급해야 합니다. 이것이 가장 확실한 대응이며, 이력을 정리하는 작업은 그 뒤의 일입니다. 저장소를 공개로 바꾸기 전에는 이력 전체에 비밀 값이 없는지 점검하게 하고, 점검 결과는 사람이 확인합니다.

AI에게 지시하는 방법

비밀 값 규칙: API 키와 비밀번호는 코드와 대화에 쓰지 않고 환경 변수 이름으로만 참조합니다. .env는 .gitignore에 있는지 확인하고, 커밋 전에 변경 목록에 비밀 값이 포함되지 않았는지 점검합니다.

이 문장을 합의서의 제약에 한 줄로 넣어 두면 세션마다 반복해서 말할 필요가 없습니다.

배포와 되돌리기

배포 대상은 작업에 따라 다릅니다. 웹 서비스라면 호스팅 서비스, 도구라면 사내 공유 위치, 문서라면 공유 폴더일 수 있습니다. 어떤 대상이든 다음 세 가지는 같습니다.

올리기 전

• 테스트와 빌드가 통과했는가
• 비밀 값이 코드나 이력에 들어가지 않았는가
• 지금 운영 중인 버전이 무엇인지 기록했는가. 이것이 되돌릴 대상입니다.
• 배포 후 확인할 항목(주소 접속, 핵심 기능 하나, 오류 로그)을 정했는가

올린 직후

배포가 성공했다는 메시지는 확인의 끝이 아닙니다. 공개 주소에 실제로 접속해 핵심 기능을 하나 이상 눌러 보고, 오류가 없는지 확인합니다. 로그인하지 않은 시크릿 창에서 열면 공개 상태에서 무엇이 보이는지 그대로 알 수 있습니다. 호스팅 서비스마다 배포 이력과 이전 배포로 되돌리는 기능을 제공하는 경우가 많으므로, 사용하는 서비스에서 되돌리는 방법을 배포하기 전에 한 번 확인해 둡니다.

문제가 생겼을 때

1. 먼저 되돌립니다. 원인 분석은 되돌린 뒤에 합니다.
2. 이전 버전으로 복구된 것을 공개 주소에서 확인합니다.
3. 무엇이 문제였는지 기록하고, 같은 문제가 반복되지 않도록 검증 항목에 추가합니다.

배포는 되돌리기 어려운 결정에 속하므로 19장에서 말한 대로 최종 확인은 사람이 합니다. AI에게 배포를 맡기는 경우에도 "배포 직전에 점검 결과를 보고하고 내 승인을 받은 뒤에 실행한다"는 조건을 둡니다.

쓰고 난 뒤의 정리

공용 컴퓨터이거나 더 쓰지 않을 도구는 퇴장 절차를 밟습니다. 앱과 배포 서비스에서 로그아웃하고, 필요하면 프로그램을 제거하고, 작업 폴더와 설정 폴더에 남은 파일을 정리합니다. 폴더를 지우기 전에 복사해 두어야 하며, 이미 올린 주소는 앱을 지워도 그대로 열린다는 점을 기억합니다. 처음 만드는 사람을 위한 순서는 6장에 있습니다.

세션 사이의 인계

긴 작업은 한 세션에서 끝나지 않습니다. 대화가 길어지면 앞의 내용이 흐려지고 응답이 느려지므로, 중간에 새 세션으로 옮기는 것이 정상입니다. 이때 필요한 것이 인계 문서입니다. 인계 문서가 없으면 새 세션은 처음부터 다시 파악해야 하고, 그 시간이 낭비됩니다.

인계 문서에 담을 것

• 변경한 것: 이번 세션에서 바꾼 파일과 내용
• 유지할 것: 바꾸면 안 되는 결정과 제약
• 하지 않은 것: 이번에 일부러 손대지 않은 범위
• 다음에 할 일: 새 세션이 가장 먼저 해야 하는 일과 확인 명령

변경, 유지, 범위 밖의 세 축으로 적으면 새 세션이 무엇을 건드려도 되는지 바로 알 수 있습니다. 진행 상황은 별도의 진행 기록 파일에 한 줄씩 남기고, 세션이 끊겨도 그 파일을 읽으면 이어갈 수 있게 합니다.

진행 기록과 이유 기록을 나누기

인계 문서와 별개로, 폴더에 두 파일을 따로 남기는 운영이 효과적입니다. PROGRESS.md에는 지금 어디까지 했고 다음 시작점이 무엇인지를 적고, HISTORY.md에는 무엇을 왜 그렇게 정했는지를 한 줄씩 적습니다. 앞의 것은 이어서 할 때 읽고, 뒤의 것은 되돌아가야 할 때 근거로 읽습니다. 둘을 섞으면 진행 상황은 길어지고 결정의 이유는 묻힙니다.

세션을 닫기 전에는 PROGRESS.md를 먼저 갱신합니다. 이어서 할 세션은 그 파일을 읽고 현재 상태부터 말하게 합니다. 쓰던 세션은 사정을 다 알아서 처음 읽는 사람이 걸리는 곳을 놓치기 쉽습니다. 그래서 일이 끝나면 쓰던 세션을 닫고, 같은 폴더에서 새 세션을 열어 검토만 시킵니다. 이때 문서를 고치지 말고 의견만 파일로 남기게 하면, 반영은 그 의견을 보고 사람이 지시합니다. 검증 방법은 19장에서 더 다룹니다.

언제 새 세션으로 넘어가는가

한 세션이 길어졌다는 신호는 다음과 같습니다.

• 앞에서 정한 제약을 어기기 시작한다
• 같은 설명을 반복해서 요구한다
• 응답이 눈에 띄게 느려진다

이런 신호가 보이면 인계 문서를 작성하고 새 세션을 엽니다. 작업 단위 하나가 끝난 지점에서 넘어가는 것이 가장 깔끔합니다. 자동 요약 기능이 있는 환경이라도 중요한 결정은 문서로 따로 남기는 편이 안전합니다.

품질 파이프라인 카드

액티전스 프롬프트 카드 중 품질 파이프라인 카드는 검증 단계를 한 번에 돌리는 카드입니다. 테스트 보강, 코드 리뷰, 정리의 세 단계로 이루어지며, 앞 단계가 끝나야 뒤 단계로 갑니다.

• 시작 전에 작업 대상의 종류(웹 앱, 도구, 라이브러리 등)와 쓸 수 있는 검사 명령을 코드에서 직접 찾아 한 줄로 기록합니다. 정의되어 있지 않은 명령은 실행하지 않습니다.
• 해당하지 않는 검사는 사유와 함께 제외합니다. 예를 들어 화면이 없는 도구에는 화면 비교 검사를 적용하지 않습니다.
• 테스트가 없는 코드는 먼저 테스트로 감싸고, 리뷰를 마친 뒤에만 정리합니다.

새 기능을 만든 뒤 안정화하거나 오래된 코드를 다듬을 때 쓰는 카드입니다. 사용법은 카드를 입력창에 붙여 넣고 그 아래에 "결제 모듈 안정화"처럼 작업 대상을 한 줄 적는 것입니다(가상의 예). 전체 카드는 부록 A에서 찾을 수 있고, 라이브러리 화면에서 복사할 수도 있습니다(https://actigence.ai).

실습

실습 1. 배포 전 점검 요청

작업 중인 결과물이 있다면 배포나 공유 직전에 아래 요청을 보냅니다. AI의 점검 결과를 그대로 믿지 말고, 보고된 항목 중 두세 개는 직접 확인합니다.

배포 전 점검을 해 주세요. 실행하지 않은 것을 통과했다고 쓰지 마시고, 실제로 실행한 명령과 결과만 보고해 주세요.
1. 이 프로젝트에서 정의된 테스트·검사·빌드 명령을 찾아 실행하고 결과를 표로 보고합니다. 정의되지 않은 항목은 "없음"으로 적습니다.
2. 코드와 변경 목록에 API 키, 비밀번호, 개인정보가 들어 있는지 검색하고, .env 계열 파일이 .gitignore에 있는지 확인합니다.
3. 지금 운영 중인 버전이 무엇인지(되돌릴 대상)와 되돌리는 방법을 한 줄로 적습니다.
4. 배포 후 확인할 항목 3가지를 제안합니다.
5. 위 결과를 근거로 "배포 가능 / 보류"를 판단하되, 실제 배포는 하지 말고 제 승인을 기다립니다.

실습 2. 인계 문서 작성

오늘 한 작업을 마무리하며 새 세션으로 넘길 문서를 만듭니다.

이번 세션의 작업을 다음 세션이 처음부터 다시 파악하지 않고 이어받을 수 있도록 인계 문서를 만들어 주세요.
형식은 다음 네 섹션입니다.
- 변경한 것: 바꾼 파일과 내용
- 유지할 것: 바꾸면 안 되는 결정과 제약
- 하지 않은 것: 일부러 손대지 않은 범위
- 다음에 할 일: 가장 먼저 할 일과 확인 방법
시행착오 과정은 빼고 확정된 결과와 그 근거만 적어 주세요. 확인되지 않은 내용은 "미확인"으로 표시합니다.

PROGRESS.md와 HISTORY.md를 나누는 버전으로도 해 봅니다. 아래 프롬프트는 같은 작업을 두 파일로 남깁니다.

이번 세션의 작업을 두 파일로 남겨 주세요.
- PROGRESS.md: 목표, 상태, 결정, 다음, 막힌 것 다섯 칸으로 지금 어디까지 했고 다음 시작점이 무엇인지만 적습니다.
- HISTORY.md: 이번에 정한 것과 그 이유를 한 줄씩 적습니다.
확인되지 않은 내용은 "미확인"으로 표시하고, 파일을 만든 뒤 각 파일을 한 줄씩 설명해 주세요.

새 세션을 열고 "이어서 하자"라고만 입력해, Claude가 PROGRESS.md를 읽고 현재 상태를 먼저 말하는지 확인합니다.

실습 3. 되돌리기 연습

연습용 폴더에서 파일 하나를 만들고 커밋한 뒤, 일부러 내용을 망가뜨리고 이전 상태로 되돌려 봅니다. 중요한 파일이 있는 폴더에서는 하지 않습니다.

연습용 빈 폴더에서 git 저장소를 만들고, 메모 파일 하나를 만들어 커밋해 주세요. 그다음 파일 내용을 일부러 바꾸고 커밋한 뒤, git revert로 직전 변경을 되돌려 주세요. 각 단계에서 실행한 명령과 git log --oneline 결과를 보여 주고, 무슨 일이 일어났는지 비전문가 눈높이로 설명해 주세요.

정리

• 작업은 준비, 개발, 검증, 배포의 네 단계로 보고, 각 단계의 산출물을 남깁니다. 만들기, 보관, 주소, 데이터는 Claude Code, GitHub, 호스팅 서비스, 구글 시트가 나눠 맡습니다.
• git의 커밋은 되돌릴 지점입니다. 변경 전에 커밋하고, 한 커밋에는 한 목적만 담습니다.
• 비밀 값은 코드와 대화에 쓰지 않고 환경 변수에 두며, 공개 저장소에 올라갔다면 키를 폐기하고 새로 발급합니다.
• 배포는 점검, 공개 주소 확인, 되돌릴 대상 기록을 한 세트로 하고, 문제가 생기면 원인 분석보다 되돌리기가 먼저입니다.
• 세션 사이에는 변경, 유지, 범위 밖, 다음 할 일을 담은 인계 문서로 이어가고, 진행 기록과 이유 기록은 파일을 나눠 남깁니다.