에이전트에게 문서를 써 달라고 하거나 코드를 고쳐 달라고 하면, 화면 안에서는 일이 끝난 것처럼 보입니다.
초안이 생겼고, 테스트도 통과했고, 답변도 그럴듯합니다. 하지만 다음 질문을 던지는 순간 빈틈이 드러납니다.
“이 결과가 실제 업무의 어느 버전인가?”
누가 만들었는지, 어떤 원본을 읽었는지, 어떤 검증을 거쳤는지, 무엇이 바뀌었는지, 문제가 생기면 어느 상태로 돌아갈 수 있는지를 설명하지 못한다면 결과물은 아직 운영 가능한 결과가 아닙니다. 파일이 존재하는 것과 업무가 이어지는 것은 다른 일입니다.
앞선 글에서 에이전트의 기억과 지식을 원본·정리된 노트·검색 인덱스·실행 컨텍스트로 나누어 보았습니다. 오늘은 그 컨텍스트에서 만들어진 결과가 GitHub와 배포 파이프라인을 지나 다시 확인 가능한 상태가 되는 과정을 살펴보겠습니다.
1. 결과물과 운영 결과 사이에는 추적 경로가 있다
에이전트가 만든 결과는 대개 여러 재료가 섞인 산출물입니다.
- 사용자가 처음 입력한 목표와 범위
- 에이전트가 읽은 파일과 외부 자료
- 실행한 명령과 도구
- 사람이 수정하거나 보류한 판단
- 최종적으로 저장·배포된 파일
이 중 마지막 파일만 남기면 결과는 빠르게 만들어졌어도 다시 설명하기 어렵습니다. 같은 질문을 다시 받았을 때 “왜 이 문장이 들어갔는가?”, “왜 이 코드가 이 버전인가?”에 답하려면 결과 앞뒤의 경로가 함께 보존되어야 합니다.
저는 이 경로를 다음처럼 단순화해 봅니다.
사용자 목표
→ 작업 공간에서 초안·변경 생성
→ 검증과 사람의 확인
→ 커밋으로 상태 고정
→ Actions가 동일한 기준으로 빌드·테스트
→ 산출물 보관 또는 배포
→ 배포 이력과 다음 변경으로 연결
여기서 GitHub는 단순한 파일 저장소가 아닙니다. 어떤 변경이 어떤 기준점에서 시작되었는지 표시하는 작업의 원장에 가깝습니다. 모든 판단을 Git 커밋에 적을 수는 없지만, 적어도 최종 결과가 어느 커밋에 해당하는지는 알려 줄 수 있어야 합니다.
아키텍처 교훈 ① 운영 가능한 결과는 파일 하나가 아니라, 목표·변경·검증·배포를 다시 따라갈 수 있는 추적 경로다.
2. 워크스페이스는 결과를 만드는 작업대다
에이전트 작업에서 워크스페이스는 단순히 현재 폴더를 뜻하지 않습니다. 어떤 규칙을 읽고, 어떤 자료에 접근하며, 어느 범위까지 수정할 수 있는지를 정하는 작업대의 경계입니다.
예를 들어 블로그 글을 작성한다고 해 보겠습니다. 에이전트가 해야 할 일은 해당 프로젝트의 작성 규칙과 기존 글을 확인하고, 새 게시물을 만들고, 로컬 빌드를 실행하는 것까지일 수 있습니다. 그러나 사용자가 명시하지 않았다면 원격 저장소에 푸시하거나 외부 게시를 자동으로 이어 가서는 안 됩니다.
이 차이를 흐리면 “작업 완료”의 기준도 흔들립니다.
| 상태 | 의미 | 다음 단계 |
|---|---|---|
| 작업 중 변경 | 로컬에서 초안이나 코드가 수정된 상태 | diff와 검증 확인 |
| 검증된 변경 | 빌드·테스트와 사람의 검토를 통과한 상태 | 커밋·PR 준비 |
| 버전 고정 | 특정 커밋으로 결과가 식별되는 상태 | Actions 실행 |
| 배포 후보 | 빌드 산출물과 검증 기록이 있는 상태 | 승인된 환경에 전달 |
| 운영 중 | 외부 서비스가 해당 버전을 제공하는 상태 | 모니터링·롤백 준비 |
이 상태를 한 번에 건너뛰면 편해 보이지만, 오류가 생겼을 때 어느 지점에서 잘못되었는지 찾기 어려워집니다. 반대로 작업 공간, 저장소, 빌드, 배포를 서로 다른 상태로 나누면 에이전트가 무엇을 했고 아직 하지 않은 일이 무엇인지 분명해집니다.
3. 커밋은 단순한 저장이 아니라 기준점을 만든다
에이전트가 파일을 여러 번 수정하는 동안 화면에는 많은 중간 상태가 지나갑니다. 그중 어떤 상태를 실제 기준으로 삼을지 정하지 않으면, 나중에 “마지막으로 잘 되던 버전”을 찾는 일부터 다시 해야 합니다.
커밋은 이 문제를 해결하는 가장 작은 단위입니다. 커밋에는 최소한 다음 질문에 답할 수 있는 정보가 남아야 합니다.
- 무엇을 바꾸었는가?
- 왜 바꾸었는가?
- 어떤 검증을 실행했는가?
- 이 변경의 범위에 포함되지 않은 것은 무엇인가?
커밋 메시지 하나가 모든 맥락을 담을 필요는 없습니다. 관련 이슈, 검토 메모, 테스트 결과, 변경 파일이 서로 연결되면 됩니다. 중요한 것은 에이전트가 만든 변경도 사람이 만든 변경과 같은 버전관리 규칙 안에 들어오는 것입니다.
특히 문서와 코드가 함께 움직이는 프로젝트에서는 “글만 바뀌었다”고 생각하기 쉽습니다. 하지만 템플릿, CSS, 검색 데이터, 빌드 설정이 결과에 영향을 줄 수 있습니다. 따라서 최종 결과를 판단할 때는 게시물 파일뿐 아니라 결과를 재현하는 데 필요한 변경 범위를 함께 확인해야 합니다.
4. Actions는 자동 실행기가 아니라 실행 가능한 작업 기록이다
GitHub Actions를 단순히 “커밋하면 알아서 배포하는 기능”으로만 보면 중요한 부분을 놓치게 됩니다. 워크플로는 어떤 이벤트에서 시작하고, 어떤 환경에서, 어떤 순서로 빌드·테스트·배포하는지를 코드로 남긴 실행 가능한 작업 절차입니다.
좋은 워크플로에는 다음 흐름이 보입니다.
변경 감지
→ 의존성·실행 환경 준비
→ 빌드
→ 테스트·정적 검사
→ 결과물 저장
→ 승인된 배포 환경에 전달
이렇게 구성하면 “내 컴퓨터에서는 됐다”는 설명을 줄일 수 있습니다. 어떤 커밋이 어떤 워크플로를 통과했는지, 빌드가 실패했는지, 결과물이 어디에 남았는지를 다음 사람이 확인할 수 있기 때문입니다.
GitHub Actions 워크플로 산출물 문서는 빌드·테스트 결과를 아티팩트로 보관하고 다른 작업에서 공유하는 방식을 설명합니다. 이 산출물은 단지 배포 파일만을 뜻하지 않습니다. 로그, 테스트 결과, 커버리지, 디버깅 자료도 다음 판단에 필요한 운영 기록이 될 수 있습니다.
따라서 에이전트가 만든 결과를 Actions에 넘길 때는 “실행해 줘”보다 다음과 같이 설계하는 편이 좋습니다.
- 어떤 커밋을 대상으로 하는가
- 어떤 명령을 실행하는가
- 성공을 무엇으로 판단하는가
- 실패 시 어떤 로그와 산출물을 남기는가
- 배포 전 어떤 승인이나 환경 조건을 요구하는가
5. 배포는 마지막 버튼이 아니라 별도의 환경이다
빌드가 성공했다고 해서 곧바로 운영 배포를 해도 된다는 뜻은 아닙니다. 빌드는 “이 소스가 정해진 절차를 통과했는가”를 확인하는 단계이고, 배포는 “이 결과를 외부 상태로 바꿔도 되는가”를 결정하는 단계이기 때문입니다.
GitHub Actions의 배포 환경은 staging이나 production처럼 대상을 분리하고, 환경별 비밀정보와 배포 보호 규칙을 적용하는 구조를 제공합니다. 필요한 경우 특정 작업 전에 필수 검토자를 두어 승인 이후에만 다음 단계가 진행되도록 할 수도 있습니다.
이 구조를 업무에 적용하면 다음처럼 역할을 나눌 수 있습니다.
| 단계 | 자동화의 책임 | 사람의 책임 |
|---|---|---|
| 빌드 | 정해진 명령으로 결과 생성 | 빌드 기준과 의존성 검토 |
| 테스트 | 반복 가능한 검사 실행 | 검사 범위가 충분한지 판단 |
| 스테이징 | 후보 버전 제공 | 화면·내용·기능 확인 |
| 운영 배포 | 승인된 버전 전달 | 외부 공개 시점과 위험 승인 |
| 롤백 | 이전 버전으로 되돌릴 절차 실행 | 되돌릴 기준과 후속 조치 결정 |
에이전트는 배포 후보를 준비하는 데 매우 유용합니다. 변경 목록을 요약하고, 테스트를 실행하고, 예상되는 영향 범위를 정리할 수 있습니다. 하지만 외부 공개가 적절한지, 고객이 보게 될 문장이 맞는지, 장애가 발생했을 때 감수할 수 있는지까지 자동으로 책임질 수는 없습니다.
6. 변경 이력은 운영의 기억이다
앞선 글에서 지식 저장소를 설명하며 “기억도 종류별로 저장해야 한다”고 적었습니다. 운영 단계에서 Git과 Actions의 기록은 그중 사건 기억과 근거 기억을 담당합니다.
- 어떤 커밋이 배포되었는가
- 어떤 워크플로 실행이 성공·실패했는가
- 어떤 산출물이 생성되었는가
- 누가 배포를 승인했는가
- 문제가 생긴 뒤 어느 버전으로 돌아갔는가
이 기록이 있으면 장애나 오류가 생겨도 “누가 잘못했는가”를 먼저 찾기보다, 어느 변경부터 결과가 달라졌는가를 확인할 수 있습니다. 기록의 목적은 책임을 한 사람에게 몰아주는 것이 아니라, 다음 판단의 출발점을 만드는 데 있습니다.
물론 모든 로그를 영원히 보관해야 한다는 뜻은 아닙니다. 로그에도 보존 기간, 접근 권한, 민감정보 마스킹 규칙이 필요합니다. 운영 기록에 비밀정보가 섞이면 재현성의 장치가 오히려 노출 경로가 될 수 있습니다.
아키텍처 교훈 ② 변경 이력은 과거를 감시하기 위한 장부가 아니라, 현재 버전을 설명하고 다음 버전을 안전하게 만드는 운영의 기억이다.
7. 에이전트의 결과를 넘길 때 확인할 최소 목록
모든 프로젝트가 거대한 CI/CD 체계를 필요로 하지는 않습니다. 작은 블로그나 개인 프로젝트라면 다음 정도부터 시작해도 충분합니다.
[ ] 변경 파일과 요청 범위가 일치하는가
[ ] 원본과 생성물을 구분했는가
[ ] 빌드·테스트 결과를 확인했는가
[ ] 결과를 특정 커밋으로 식별할 수 있는가
[ ] 실패 로그와 필요한 산출물이 남아 있는가
[ ] 운영 배포 전에 사람이 확인할 지점이 있는가
[ ] 문제가 생기면 되돌릴 버전과 절차가 있는가
이 목록의 핵심은 자동화를 많이 넣는 것이 아닙니다. 에이전트가 만든 결과가 다음 시스템으로 넘어갈 때 상태가 사라지지 않게 하는 것입니다.
초안은 초안으로, 검증본은 검증본으로, 배포본은 배포본으로 식별되어야 합니다. 각각을 구분하면 에이전트에게 더 많은 일을 맡기면서도 사람이 확인해야 할 지점을 좁힐 수 있습니다.
마치며
에이전트가 결과를 만드는 속도는 계속 빨라질 겁니다. 그래서 앞으로의 경쟁력은 결과를 빨리 만드는 능력만이 아니라, 그 결과를 다시 만들고, 설명하고, 고치고, 되돌릴 수 있는 능력에 달려 있습니다.
GitHub는 변경의 기준점을 만들고, Actions는 반복 가능한 실행 절차를 기록하며, 아티팩트는 빌드와 테스트의 결과를 이어 줍니다. 배포 환경과 승인 규칙은 검증된 결과가 외부 상태로 바뀌는 순간을 분리합니다. 이 요소들이 연결될 때 에이전트의 초안은 운영 가능한 결과로 성장합니다.
다음 글에서는 자동화의 속도를 더 높이는 문제를 다뤄 보겠습니다. 모든 단계를 자동으로 연결하는 것이 목표라면, 권한·비밀정보·데이터 전송·비용·감사 로그를 어디에서 멈추게 해야 할까요? 빠른 자동화와 안전한 운영 사이에는 없애야 할 벽이 아니라, 업무가 오래 지속되도록 설계해야 할 경계선이 있습니다.