Jira에서의 사양 주도 개발
사양 기반 개발은 에이전트가 빌드하기 전에 구조화된 스펙을 작성하여, 그럴듯한 추측 대신 정확한 결과물을 만들도록 하는 것을 의미합니다. Jira에서 사양은 결과, 범위, 제약 조건 및 수용 기준과 같은 실제 의도를 포함하게 되면 이미 작업 중인 업무 항목에 포함됩니다. 업무 항목은 하나의 작업에 대한 전체 사양을 포함하거나, 여러 업무 항목에 걸쳐 분할된 더 큰 기능 사양의 일부를 포함할 수 있습니다.
이 가이드는 사양을 에이전트 준비 상태로 만드는 요소, 업무 항목이 사양을 작성하기에 적합한 공간인 이유, 그리고 첫 번째 사양을 작성하는 방법을 다룹니다. 간단히 말해, Jira의 사양 기반 개발은 다음 세 가지를 제공합니다.
에이전트가 구축의 기반으로 삼고 검토자가 대조하여 확인하는 단일 정보 출처
에이전트와 사용자 모두에게 완료를 정의하는 수용 기준
에이전트가 코드 한 줄을 작성하기도 전에 의도가 확정되므로 재작업 감소
사양 기반 개발이란 무엇입니까?
사양 기반 개발은 한 줄의 프롬프트로 추측하는 대신, 무엇을 빌드할지 및 성공을 어떻게 측정할지 정의하는 구조화된 스펙을 작성하고 에이전트가 이것을 구현하는 방식입니다.
사양이 정보 출처가 됩니다. 사양은 계획, 빌드 및 확인을 주도하며, Jira에서는 이 세 가지가 모두 동일한 업무 항목에서 이루어집니다. 이 아이디어는 빌드하기 전에 동작을 정의하는 API 설계 및 정형 기법 관행에서 발전한 것으로, AI보다 앞서 등장했습니다.
도구가 발전함에 따라 정의가 계속 바뀌므로, 고정된 사양 형식보다는 하나의 관행으로 생각하세요. 변하지 않는 핵심은 에이전트가 업무를 구축하기 전에 미리 정의해야 한다는 점입니다.
차이는 모호함을 해결하는 시점에 달려 있습니다. 바이브 코딩은 코드가 작성된 후에 모호함을 해결하고 사양 주도 개발은 코드 작성 전에 해결합니다.
바이브 코딩: 프롬프트로 에이전트를 유도하고 에이전트가 반환하는 결과를 수용하므로, 에이전트가 가정한 범위, 제약 조건 및 예외적 사례는 코드가 만들어진 후에 드러납니다.
사양 주도 개발: 의도, 제약 조건 및 수용 기준을 먼저 확정하여 에이전트가 추측이 아닌 정의에 따라 구축하도록 합니다. 검토 단계에서도 해당 정의가 포함된 업무 항목에서 동일한 정의를 기준으로 확인합니다.
실제 코드베이스에서 유지되어야 하는 코드의 경우, 확립된 컨텍스트가 없는 에이전트는 티켓을 너무 문자 그대로 해결하여 중요한 제약 조건을 놓칠 수 있습니다. 바로 여기서 재작업이 발생합니다.
사양은 만드는 대상에 대한 것이고 계획은 만드는 방법에 대한 것인데, 프롬프트는 종종 이 두가지를 모호하게 만듭니다. 스펙 주도 개발은 만들 대상을 먼저 결정한 다음, 이를 기반으로 만드는 방법을 구축합니다. 이는 AI 코딩 도구의 계획 모드에서 종종 건너뛰는 단계로, 대개 사전에 합의된 사양 없이 프롬프트로부터 바로 구현 방법을 작성합니다.
계획 모드는 가벼운 사양 역할을 대신할 수 있지만, 업무에 지속적으로 유지되는 합의된 사양이 아니라 그 순간 프롬프트로부터 '방법'을 작성하는 방식입니다.
AI 코딩에서 사양이 중요한 이유
코드 생성이 저렴해진 시대에 가장 어려운 부분은 더 이상 코딩이 아니라 올바른 구축 대상을 정의하는 것입니다. 그렇기 때문에 프롬프트가 아니라 사양이 여러분이 제작하는 가장 영향력 있는 산출물이 됩니다.
단발성 프롬프트는 에이전트에게 공백을 남겨두며 에이전트는 이를 가정으로 채워 그럴듯해 보이지만 엉뚱한 문제를 해결하는 코드를 생성합니다. 반면 사양은 그러한 공백을 사전에 해소하므로, 에이전트는 추측이 아닌 정의에 따라 코드를 구축하게 됩니다. Jira에서 이 사양은 팀이 이미 계획하고 할당하며 검토하는 업무 항목입니다.
에이전트가 구축할 수 있는 사양에 포함되는 내용
에이전트 준비 사양은 훌륭한 엔지니어가 개발을 시작하기 전에 던질 만한 질문들에 답을 제공합니다. Jira에서는 업무 항목의 요약, 설명, 연결된 요구 사항, 수용 기준에 이러한 내용이 담깁니다. 중요 요소는 다음 6가지입니다.
결과: 검토자가 확인할 수 있는 관점에서 변경 사항이 달성해야 하는 목표입니다.
범위: 포함되는 항목 및 제외되는 항목으로, 이 두 가지는 동일하게 중요합니다.
제약 조건: 준수해야 할 아키텍처, 보안 및 성능 한도입니다.
이전 결정 사항: 에이전트가 불필요하게 다시 논의하지 않도록 이미 합의된 컨텍스트입니다.
작업 세분화: 확인하기에 충분히 작은 단계로 나뉜 업무입니다.
수용 기준: 에이전트가 구축하고자 하며 검토의 기준이 되는, 테스트 가능한 완료의 정의입니다. Jira에서는 업무 항목에 위치하며, AI 코드 검토를 통해 담당자가 확인하기 전에 이 조건에 맞춰 변경 사항을 검토할 수 있습니다.
Jira에서 업무 항목이 사양이 되는 방법
잘 구성된 업무 항목은 에이전트가 구축하고 검토하는 기준 사양 역할을 할 수 있습니다. 사양은 많은 SDD 도구들처럼 연결된 문서 안에 존재할 수도 있지만, Jira는 업무가 이미 진행되는 곳에 사양이 위치하도록 합니다. 앞서 언급한 6가지 요소를 갖출 때 사양 등급이 되며 한 줄짜리 '로그인 버그 수정'과 같은 업무 항목은 사양에 해당하지 않습니다.
사양을 업무 항목에 유지하면 업무가 이미 진행되는 곳에 위치하므로, 아무도 다시 열어보지 않는 리포지토리의 마크다운 파일보다 방치되기 어렵다는 구조적 장점이 있습니다. 그렇다고 해서 자체 유지 관리가 되는 것은 아니며, 단지 사양과 업무 내용이 서로 어긋나지 않음을 의미합니다.
모든 요소의 통합: 요약, 설명, 연결된 Confluence 요구 사항, 수용 기준이 한곳에 모여 있어 에이전트와 검토자 모두가 읽을 수 있습니다.
반면에 리포지토리 파일은 업무가 추적, 검토, 완료되는 곳과 떨어져 있어 계획이 바뀌는 순간 오래된 정보가 됩니다.
에이전트가 작업을 완료하면 동일한 업무 항목이 검토 공간이 되며, 팀이 요구 사항과 미해결 질문에 대해 의견을 조율하는 장소가 됩니다.
Jira는 명확한 요구 사항, 작업 및 추정치가 포함된 계획을 정의합니다.
Jira 플래너가 구조화된 사양을 생성하는 방법
이전 섹션에서는 하나의 업무 항목을 직접 사양으로 전환하는 기본 방법을 다루었습니다. Jira 플래너는 여러 팀에 걸친 복잡한 이니셔티브를 위한 기능으로, 모든 사양을 수동으로 작성하는 것은 확장성이 떨어지기 때문에 활용됩니다. 이니셔티브에서 시작하여 각각 고유한 사양을 가진 구조화된 업무 항목으로 세분화합니다.
Jira 플래너는 기준선이 아닌 가속기 역할을 합니다. 기준선 SDD 방법론은 잘 구성된 업무 항목에 수용 기준을 더한 것이며, 현재 모든 팀이 이를 바로 적용할 수 있습니다. Jira 플래너는 해당 업무의 가장 어려운 부분인 복잡하고 모호한 요청을 구조화된 사양으로 변환하는 과정을 가속합니다.
복잡한 프로젝트의 경우, Jira 플래너는 코드베이스, Jira 및 Confluence 기록, 팀 컨텍스트를 포함한 Teamwork Graph를 활용하여 요구 사항을 정의하고 개발자 또는 코딩 에이전트가 빌드할 수 있도록 Confluence에서 구조화된 기술 사양을 생성합니다. 하나의 계획으로 사람이 읽기 쉬우면서 에이전트에게도 유용한 산출물을 제공합니다.
역할:
사용자와 팀이 공동 작업할 수 있는 공유 공간을 제공하여, 에이전트가 실행되기 전에 미리 정렬할 수 있습니다.
사용자의 모든 업무에서 컨텍스트를 가져오므로, 빈 프롬프트 대신 팀이 이미 알고 있는 내용에서 사양이 시작됩니다.
사람이 읽기 쉽고 에이전트가 명확하게 구문 분석할 수 있는 사양을 생성하므로, 동일한 아티팩트로 검토 및 실행을 모두 수행할 수 있습니다.
사양을 Confluence에 유지하고 작업에 연결하여 의도 및 결정 사항을 기록으로 남깁니다.
Jira 플래너는 대략적인 아이디어를 에이전트가 바로 사용할 수 있는 구조화된 사양으로 변환합니다.
Jira 플래너는 얼리 액세스 단계에 있습니다 — 대기 목록에 등록하세요
Jira에서 첫 번째 에이전트 준비 사양을 작성하는 방법
6가지 요소를 체크리스트로 활용해 하나의 업무 항목을 직접 에이전트 준비 사양으로 변환해 보세요.
업무 항목에서 시작합니다. 설명에 단순한 제목뿐만 아니라 결과, 범위 경계 및 제약 조건을 포함합니다.
의도를 구조화된 사양으로 변환합니다. 실제 SDD 업무입니다. 이전 컨텍스트를 업무 항목의 결과, 범위 및 제약 조건으로 구체화하여 에이전트가 정의를 상속받도록 합니다.
테스트 가능한 수용 기준을 작성합니다. 에이전트가 구현하고 검토자가 대조하여 확인하는 계약입니다. 대부분의 기준은 테스트가 가능해지기 전에 몇 번의 수정이 필요합니다.
코딩 에이전트에 할당합니다. 사양 등급의 업무 항목을 통해 에이전트가 항목에 연결된 풀리퀘스트를 구현하고 열 수 있는 충분한 정보를 제공합니다.
기준에 따라 풀리퀘스트를 검토한 다음 개선합니다. 에이전트가 추측한 부분을 보완하도록 사양을 다듬고 다음 업무 항목에 이 패턴을 다시 사용합니다.
사양 주도 개발에 대해 자주 묻는 질문
사양 주도 개발을 위해 Jira 플래너가 필요합니까?
아닙니다. 기준선은 수용 기준을 갖춘 잘 구성된 업무 항목이며, 어떤 팀이든 지금 바로 작성할 수 있습니다. 다만 복잡한 작업의 경우, Jira 플래너는 최상위 계획이나 이니셔티브에서 시작해 이를 구조화된 Jira 업무 항목들로 세분화하고 각각의 사양을 자동으로 채워주므로 모든 것을 수동으로 작성하는 번거로움을 덜어줍니다.
사양과 수용 기준의 차이점은 무엇입니까?
사양은 결과, 범위, 제약 조건 및 컨텍스트 등 변경 사항 전체를 정의합니다. 수용 기준은 사양의 한 부분으로, 에이전트가 목표로 삼아 구축하고 검토자가 이를 기준으로 확인하는 테스트 가능한 완료의 정의입니다.
잘 작성된 프롬프트만으로 충분합니까?
작고 되돌릴 수 있는 업무의 경우, 대개 충분합니다. 복잡하거나 되돌리기 어려운 작업의 경우, 에이전트가 사용자가 프롬프트에서 누락한 내용을 추측해야 합니다. 사양은 이러한 추측의 필요를 없애줍니다.
사양은 리포지토리 파일에 있어야 합니까, 아니면 Jira 업무 항목에 있어야 합니까?
업무가 추적, 검토 및 종료되는 업무 항목에 사양을 두는 것이 좋습니다. 이렇게 하면 아무도 다시 열어보지 않는 리포지토리의 마크다운 파일보다 내용이 어긋날 가능성이 적습니다.
사양 주도 개발이 팀의 속도를 늦춥니까?
초기에는 노력이 더 들지만 나중에 다시 작업하는 과정을 없애줍니다. 복잡한 업무에서는 이러한 맞바꿈이 이득이 됩니다. 사소한 수정이라면 사양 작성을 건너뛰고 바로 프롬프트를 작성하는 것이 좋습니다.
사양을 언제 작성해야 하고, 언제 건너뛰어야 합니까?
복잡하거나 영향력이 크거나 되돌리기 어려운 업무, 또는 실제 아키텍처 또는 보안 제약이 있는 모든 사항에 대해 사양을 작성합니다. 간단한 프롬프트로 더 빠르게 처리할 수 있는 작고 되돌릴 수 있는 수정 사항의 경우 사양 작성을 건너뛰어도 됩니다.