코딩 에이전트는 짧은 지시만으로 화면과 코드를 빠르게 만들 수 있습니다. 그러나 실제 개발에서 가장 비용이 큰 문제는 코드 작성 속도가 아니라, 무엇을 만들어야 하는지 오해하고, 기존 규칙을 놓치고, 검증 없이 완료라고 판단하는 데서 생깁니다.
Superpowers는 코딩 에이전트가 따를 수 있는 스킬 기반 개발 방법론입니다. 공식 저장소는 아이디어 정리, 설계 승인, 구현 계획, 테스트 주도 개발, 코드 리뷰, 완료 전 검증을 하나의 기본 흐름으로 제시합니다. 이는 특정 언어나 프레임워크 기능이라기보다, 에이전트가 개발 업무를 수행하는 순서를 통제하는 방식에 가깝습니다.
에이전트의 ‘코드 생성’과 ‘개발 수행’은 다릅니다
코드 생성은 요청을 받고 파일을 수정하는 일입니다. 개발 수행은 그 전에 문제와 제약을 확인하고, 이후 변경이 요구사항을 만족하는지 검증하는 일입니다.
| 단계 | 코드 생성 중심 접근 | 개발 수행 중심 접근 |
|---|---|---|
| 시작 | 바로 구현 | 문제·사용자·제약을 확인 |
| 설계 | 대화 안의 추정 | 검토 가능한 설계와 결정 기록 |
| 구현 | 큰 변경을 한 번에 생성 | 작은 작업 단위로 실행 |
| 검증 | 화면 확인 또는 빌드만 실행 | 테스트·리뷰·요구사항 대조 |
| 완료 | 에이전트의 선언 | 증거를 확인한 뒤 사람이 판단 |
Superpowers가 강조하는 브레인스토밍, 계획, 작업 공간 분리, TDD, 리뷰, 완료 전 검증은 두 번째 방식을 에이전트에게 강제하려는 장치입니다.
AX·DX 개발에서는 왜 순서가 중요할까
DX 플랫폼은 화면 하나만 바꾸는 작업이 아닙니다. 업무 데이터, 역할·권한, 승인 조건, 상태 변화, 이력·증적, 기존 시스템 연동이 함께 움직입니다. 에이전트가 한 부분만 보고 코드를 고치면 다음과 같은 문제가 생길 수 있습니다.
- 승인 화면은 바뀌었지만 권한 검사가 누락된다.
- 상태 전이는 추가됐지만 감사 이력이 남지 않는다.
- 자동화가 동작하지만 예외 처리와 되돌림 기준이 없다.
- UI 테스트는 통과했지만 기존 시스템 연동 규약이 깨진다.
따라서 개발 에이전트에게는 “코드 작성”보다 먼저 업무 규칙을 읽고, 변경 영향 범위를 확인하고, 검증 방법을 계획하게 해야 합니다.
실무에 적용할 수 있는 최소 흐름
Superpowers의 전체 방법론을 그대로 도입하지 않아도, 다음 다섯 단계를 팀 표준으로 삼을 수 있습니다.
- 문제 정의: 누가 어떤 업무에서 무엇을 바꾸려는지 한 문장으로 합의합니다.
- 변경 설계: 데이터, 역할, 상태, 승인, 이력, 연동 중 영향받는 항목을 확인합니다.
- 구현 계획: 파일·작업 단위·검증 방법을 작게 나눕니다.
- 검증 실행: 테스트를 먼저 정하고, 빌드·린트·화면·연동 확인을 수행합니다.
- 리뷰와 인수: 요구사항 충족과 코드 품질을 분리해 검토하고, 증거를 남깁니다.
이 흐름은 에이전트를 쓰지 않는 팀에도 유효합니다. 에이전트를 사용할 때는 특히, 각 단계에서 사람의 판단을 건너뛰지 않게 만드는 장치가 됩니다.
스킬을 팀 표준으로 만들 때의 주의점
에이전트 스킬은 조직의 개발 규칙을 빠르게 전달할 수 있습니다. 다만 스킬 파일에 모든 지식을 넣는 것은 좋은 방법이 아닙니다.
- 보안 정책, 아키텍처 결정, 인터페이스 규약은 공식 문서와 연결합니다.
- 스킬에는 언제 어떤 문서를 읽고 어떤 검증을 해야 하는지를 적습니다.
- 프로젝트별 예외는 별도 승인과 만료일을 둡니다.
- 외부에서 가져온 스킬은 실행 전 권한·네트워크·파일 접근 범위를 검토합니다.
스킬은 개발 표준의 대체물이 아니라, 표준을 실제 작업 순서로 연결하는 실행 보조물입니다.
가상의 업무 예시: 승인 화면의 ‘빠른 수정’ 요청
승인 화면을 빠르게 고쳐 달라는 가상 요청으로 이 차이를 살펴보겠습니다. 현업이 승인 대기 목록에 긴급도 표시를 추가해 달라고 요청합니다. 에이전트가 화면 컴포넌트만 찾아 색상을 넣으면 빠르지만, 긴급도 값의 출처, 조회 권한, 정렬 기준, 이력 화면의 표시 여부는 빠질 수 있습니다. 팀은 먼저 수용 기준을 “승인자는 자기 조직의 대기 건에서만 긴급도를 보고 정렬할 수 있으며, 값 변경은 기존 업무 건 이력에 남는다”로 정합니다. 이후 데이터 조회, 권한 검사, 화면, 테스트를 각각 작은 작업으로 나누고, 변경 전후 화면과 테스트 결과를 인수 근거로 남깁니다.
| 점검 시점 | 사람이 확인할 질문 |
|---|---|
| 시작 전 | 요구사항과 영향받는 역할·상태를 읽었는가 |
| 구현 전 | 파일 단위 계획과 되돌릴 방법이 있는가 |
| 완료 전 | 수용 기준을 반증하는 테스트를 실제로 실행했는가 |
| 인수 시 | 변경 결과와 남은 위험을 책임자가 확인했는가 |
처음에는 권한·상태·외부 연동에 영향을 주는 변경에만 이 흐름을 적용해 보세요. 요청에 수용 기준, 영향 범위, 실행할 검증, 승인자를 함께 적고, 완료된 변경 몇 건을 회고해 빠진 항목을 양식에 반영합니다. Superpowers는 이 순서를 검토하는 참고 방법론일 뿐 조직의 승인과 보안 기준을 대신하지 않습니다.
계획을 실행 가능한 단위로 바꾸는 기준
에이전트에게 “승인 화면을 개선해 달라”고 요청하면 파일을 고르는 일부터 추측이 시작됩니다. 전문팀이 검토하는 계획은 화면, 데이터, 권한, 이력, 시험을 따로 나열하는 데 그치지 않습니다. 각 작업에 확인할 수용 기준과 되돌릴 방법을 연결합니다. 예를 들어 긴급도 표시 변경은 값의 출처, 조직별 조회 범위, 정렬 기준, 변경 이력, 빈 값일 때의 화면을 각각 확인 대상으로 둡니다. 이 기준이 있으면 에이전트가 만든 변경도 사람이 빠르게 반증할 수 있습니다.
가상의 배포 당일을 보겠습니다. 구현은 끝났지만 권한 검증 테스트가 실패했습니다. 이때 에이전트가 화면 결과만 보고 완료로 선언하게 두지 않습니다. 배포를 보류하고, 실패한 역할·조직·상태 조합을 작업 기록에 남깁니다. 담당자는 요구사항 자체가 모호했는지, 구현이 계약을 어겼는지, 시험 데이터가 잘못됐는지를 구분합니다. 수정 뒤에는 실패했던 조합을 회귀 시험에 넣고, 영향이 큰 변경이라면 이전 버전으로 되돌리는 조건과 담당자까지 합의합니다. 작업 속도는 이 과정을 생략해서가 아니라, 다음 변경에서 같은 판단을 재사용해서 높아집니다.
사람의 검토가 필요한 경계
- 요구사항의 우선순위와 허용할 업무 예외
- 권한·개인정보·외부 연동처럼 영향이 큰 설계 결정
- 테스트가 다루지 못한 운영 조건과 배포 승인
- 완료 증거가 부족하거나 서로 모순될 때의 종료 판단
도구의 작업 흐름은 공식 저장소의 설명을 확인해 참고할 수 있지만, 실제 적용 범위와 접근 권한은 조직의 보안·개발 운영 기준으로 별도 검토해야 합니다.
계획이 길어지는 것이 항상 좋은 것은 아닙니다. 담당자는 변경을 되돌릴 수 있는 작은 단위로 나누되, 서로 의존하는 권한·상태·연동 규칙을 임의로 분리하지 않아야 합니다. 한 작업의 시험이 실패했을 때 에이전트는 다음 작업으로 넘어가지 않고, 실패한 수용 기준과 영향 범위를 다시 확인해야 합니다. 사람은 이 시점에 요구사항을 바꿀지 구현을 고칠지 결정하며, 변경 이유는 다음 검토자가 재현할 수 있게 작업 기록에 남깁니다.
설계 승인은 구현을 멈추는 관문이 아니라 가정을 드러내는 단계입니다
에이전트는 빈칸을 만나면 그럴듯한 기본값으로 채우는 데 능숙합니다. 문제는 승인 기한, 빈 값 처리, 기존 데이터의 변환처럼 업무에 중요한 빈칸도 기술적 세부사항으로 취급할 수 있다는 점입니다. 설계 검토에서는 화면 모양보다 에이전트가 무엇을 사실로 간주했는지를 확인해야 합니다. 확인되지 않은 가정은 결정으로 바꾸지 않고 질문, 임시 제약, 검증할 위험으로 구분해 계획에 남깁니다.
가령 승인 대기 목록에 긴급도 정렬을 넣을 때 ‘긴급’ 값을 누가 만들 수 있는지가 정해지지 않았다면 구현을 시작해도 코드는 완성될 수 있습니다. 그러나 요청자가 직접 긴급도를 올릴 수 있는지, 승인자가 조정할 수 있는지, 기한이 지나면 자동으로 바뀌는지에 따라 권한과 이력이 달라집니다. 현업 책임자는 업무 의미를, 보안 담당자는 남용 가능성을, 개발자는 데이터 변경 범위를 확인한 뒤 수용 기준을 확정해야 합니다. 에이전트가 제안한 선택지는 논의를 돕지만 승인된 규칙 자체는 아닙니다.
실행 중 계획이 달라지면 변경 이유부터 다시 승인합니다
작은 작업으로 나눴더라도 구현 중에는 예상하지 못한 의존성이 나타납니다. 기존 데이터 모델로는 값을 저장할 수 없거나 공통 컴포넌트의 변경이 다른 화면에 영향을 줄 수 있습니다. 이때 에이전트가 계획 밖의 파일을 연쇄 수정하도록 두면 처음 승인한 영향 범위와 실제 변경이 달라집니다. 계획 변경은 실패가 아니라 정상적인 개발 신호이므로, 새로 발견한 사실·추가 영향·대안·검증 방법을 짧게 기록하고 사람이 계속 진행할지 결정하게 합니다.
특히 데이터 이전이나 권한 모델 변경이 새로 필요해졌다면 원래 작업과 분리할지를 판단해야 합니다. 화면 표시를 위한 요청이 과거 데이터의 일괄 갱신으로 커졌다면 되돌림 방식과 운영 중단 가능성이 완전히 달라집니다. 제품 책임자는 범위를 줄여 먼저 가치를 확인할지, 개발 책임자는 호환 계층을 둘지, 운영 담당자는 배포 창과 복구 시간을 감당할지 검토합니다. 일정이 촉박하다는 이유로 이 결정을 에이전트의 편의에 맡기면 빠른 구현이 장기적인 운영 부채로 바뀝니다.
인수는 결과물과 작업 과정을 함께 재현하는 일입니다
검토자는 최종 코드만 읽는 데서 끝내지 않고 최초 수용 기준, 승인된 설계, 실행한 작업, 계획에서 달라진 부분, 검증 결과를 한 흐름으로 따라갈 수 있어야 합니다. 시험이 통과했더라도 어떤 환경과 데이터에서 실행됐는지 알 수 없으면 재현 가능한 근거가 아닙니다. 반대로 계획과 다른 선택이 있었어도 이유와 영향, 추가 시험이 명확하다면 책임 있는 변경으로 검토할 수 있습니다.
배포 후에는 에이전트가 예상한 성공 신호와 실제 운영 신호를 비교합니다. 긴급도 정렬 기능이라면 오류 수만 볼 것이 아니라 값이 없는 기존 건이 사라지지 않는지, 다른 조직의 건이 노출되지 않는지, 정렬 때문에 승인 처리 시간이 늘지 않는지를 확인합니다. 이상이 생기면 변경 전체를 무조건 되돌리기보다 화면 기능 중지, 조회 계약 복원, 데이터 변경 보류처럼 미리 나눈 복구 단위를 사용합니다. 이 결과를 다음 계획의 입력으로 돌려보내야 작업 방식이 문서상의 절차가 아니라 팀의 개발 역량이 됩니다.
초안을 승인 가능한 변경으로 판단하는 기준은 무엇인가
개발 책임자는 에이전트가 만든 초안을 바로 병합할지 판단할 때 코드의 길이보다 변경의 경계를 봅니다. 화면 표현만 바뀌는지, 권한·데이터·외부 계약까지 바뀌는지에 따라 계획과 검증의 깊이가 달라집니다. 현업 책임자는 수용 기준을 확인하고, 개발자는 영향 파일과 회귀 위험을, 운영 담당자는 배포 뒤 확인할 신호를 검토합니다. 이 역할이 충돌할 때는 일정 압박보다 되돌릴 수 없는 영향이 있는지를 먼저 판단합니다. 작은 작업으로 나눌 수 없다면 자동화 범위도 아직 너무 큽니다.