요구사항에서 코드까지: 추적 가능한 AI 에이전트 워크플로우

요구사항에서 코드로 이어지는 과정은 에이전트 도입이 조용히 실패하는 지점이다. 에이전트가 잘못된 코드를 작성한 게 아니다. 문제는 6주 뒤에 아무도 그 변경이 어떤 요구사항에서 비롯되었는지, 누가 범위를 승인했는지, 리뷰어가 승인 전에 어떤 근거를 보았는지 보여줄 수 없다는 점이다. 코드는 빠르게 도착했다. 기록은 그렇지 않았다.

이 튜토리얼은 그 기록을 의도적으로 구축한다. 문서로 작성된 요구사항에서 병합된 풀 리퀘스트까지 이어지는 하나의 체인이며, 각 단계는 누구나 열어볼 수 있는 것이다. GitHub의 Spec Kit은 저장소 안의 파일로 같은 공백을 해결한다. 이 가이드는 작업 시스템으로 이 공백을 해결하며, Sharkly를 사용하는 이유는 전체 체인을 하나의 Task에 유지하기 때문이다. 다만 이 패턴은 동일한 링크를 담을 수 있는 어떤 트래커로든 옮길 수 있다. 운영 루프부터 먼저 보고 싶다면 AI 에이전트 프로젝트 관리 가이드부터 시작하라.

TL;DR

추적 가능한 요구사항-코드 워크플로란 모든 산출물이 자신을 만들어낸 산출물을 가리키는 것이다. 즉 요구사항, Task, 하위 태스크, 실행, 풀 리퀘스트, 승인이다. Sharkly에서는 요구사항이 Task가 되고, Agent가 Plan 모드에서 분해안을 제안하면 사람이 이를 확인한다. 각 하위 태스크는 실행 로그와 함께 격리된 워크트리에서 실행되고, 풀 리퀘스트는 Task ID로 다시 연결되며, 사람이 처음에 작성한 승인 기준에 따라 결과를 승인한다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고한다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 승인한다.

추적 가능성이 의미해야 하는 것

추적 가능성은 마지막에 생성하는 보고서가 아니다. 그것은 체인의 속성이다. 각 연결고리는 앞선 연결고리 때문에 존재하며, 어느 방향으로든 따라갈 수 있다. 기능 하나를 다루는 데는 여섯 단계면 충분하다.

어느 단계든 빠지면 그 체인은 장식에 불과하다. 가장 흔한 공백은 마지막 단계다. 아무도 변경을 요구사항과 비교하지 않았는데 병합된 풀 리퀘스트를 승인으로 간주하는 경우다.

1단계: 요구사항을 Task로 작성하기

Task는 Sharkly에서 추적되는 작업의 기본 단위이며, 소프트웨어 개발용으로 설정된 Space는 Requirement, Bug, Task, User Story 태스크 유형으로 시작한다. 상위 항목으로는 Requirement 또는 User Story를 사용하라. 유형에 따라 적용되는 사용자 정의 필드와 워크플로 상태가 결정되므로, Requirement는 Bug 워크플로를 오염시키지 않고 자체적인 리뷰 상태를 가질 수 있다.

설명이 핵심적인 역할을 한다. 대화를 한 번도 보지 못한 사람을 위해 작성하라. 작업이 왜 중요한지, 범위에 포함되는 것과 제외되는 것, 관련 파일이나 관찰된 동작, 이미 내려진 결정, 그리고 완료를 어떻게 검토할지. 그 마지막 항목이 바로 승인 기준이며, 여섯 번째 단계의 닻이다. 아직 작성할 수 없다면 그 요구사항은 준비되지 않은 것이다. Backlog가 바로 그런 용도로 존재한다. 다시 말해 Agent에 할당된 Task는 Backlog에 있는 동안 시작되지 않는다.

Space 수준에서 저장소를 연결하면 모든 하위 태스크가 이를 상속한다. 저장소 바인딩이 없는 Agent는 Space의 Git 저장소로 대체되는데, 여러 Task로 이루어진 기능에서는 이 방식이 바람직하다.

2단계: Agent가 분해 작업을 구성하게 하고, 확인하기

Task의 Agent 채팅을 열고 세션을 Plan 모드로 전환하라. Plan 모드에서 Agent는 검토용으로 작업을 제안할 수 있으며, Sharkly는 제안을 확인한 뒤에만 계획된 Task와 하위 태스크를 생성한다. 시작하지 않고 확인만 하거나, 확인하고 작업을 시작할 수 있다.

이 단계를 대부분의 팀이 건너뛰는데, 바로 이 단계가 분해 작업을 즉흥적인 것이 아니라 추적 가능하게 만든다. 제안은 작업이 되기 전에 눈에 보인다. 범위를 확장하는 하위 태스크는 제거하고, Agent가 놓친 마이그레이션 단계는 추가하라. 하위 태스크는 상위 항목과 같은 Space에 머무르며, Sharkly는 자기 자신을 부모로 지정하는 것과 순환을 거부하므로 계층 구조는 트리로 유지된다.

하나의 역할로 감당할 수 있는 요구사항에는 단일 Agent를 사용하라. Crew는 리더가 목표를 해석하고, 테스트 작성자 같은 다른 Agent 구성원을 참여시키고, 그 결과를 하나의 Task로 다시 모아야 할 때 사용하라. 파일 세 개짜리 변경이라면 Crew는 추적 가능성을 더하지 않으면서 복잡한 요소만 늘린다. Sharkly Crews 가이드에서 리더 우선 모델을 다룬다.

채팅에서 결정된 사항은 무엇이든 Task 설명에 복사하라. Task의 채팅은 댓글이 아니고 Activity에도 나타나지 않으므로, 그곳에만 존재하는 결정은 체인에서 보이지 않는다.

3단계: 추적 기록과 함께 격리된 환경에서 실행하기

Assignee 컨트롤을 통해 각 하위 태스크를 Agent에 할당한 다음 Backlog에서 빼내라. Sharkly는 상태 범주와 실행 준비 상태를 확인하고, 실행을 대기열에 넣고, 선택된 Computer로 전달한다. 그러면 그곳의 로컬 서비스가 격리된 태스크 디렉터리를 준비하고 Runtime을 시작한다.

이 단계를 견실하게 유지하는 두 가지 세부 사항이 있다. 실행에는 Task 제목과 설명, 최근 댓글, 그리고 허용된 상태가 포함된 Task 유형 Workflow가 포함되므로, Agent는 요약된 내용이 아니라 요구사항 자체를 바탕으로 작업한다. 또한 저장소를 기반으로 하는 각 실행은 Temporary 모드에서 자체 워크트리를 가지므로, 병렬로 실행되는 하위 태스크가 서로를 덮어쓸 수 없다. 병합 충돌 없이 에이전트를 병렬로 실행하기 글에서 격리가 왜 팬아웃을 안전하게 만드는지 설명한다.

진행 상황, 추적 이벤트, 결과는 Task로 돌아온다. 실행 로그에는 실행이 대기열에 들어간 이유, 시작과 종료 시각, 도구 호출과 Runtime 이벤트, 트리거 출처, 실패 세부 정보가 기록된다. 그 로그가 네 번째 단계다.

4단계: ID로 풀 리퀘스트 연결하기

GitHub 조직을 한 번 연결한 다음, Task ID를 풀 리퀘스트 제목, 설명 또는 소스 브랜치 이름에 넣어라. SH-312만 단독으로 써도, Fixes SH-312라고 써도 링크가 생성된다. 링크백은 풀 리퀘스트에 Task URL을 댓글로 달며, 비공개 저장소에서는 기본으로 켜져 있다.

이제 추적 가능성에 중요하므로 경계를 짚어보자. fixes나 closes 같은 단어는 추가적인 의미를 담지 않으며, 풀 리퀘스트를 병합해도 Task 상태는 바뀌지 않는다. Sharkly는 변경을 Task에 연결할 뿐, Task가 완료되었다고 판단하지 않는다. 상태는 사람의 결정으로 남는데, 이것이 바로 여섯 번째 단계의 핵심이다. Jira 티켓을 AI 에이전트에 할당하고 PR을 받아내기 워크스루에서 트래커 쪽에서 동일한 연결을 보여준다.

5단계: 요구사항에 비추어 검토한 뒤 승인하기

Agent는 Task를 사람의 리뷰를 기다리는 상태로 남겨둘 수 있으며, 그 신호는 담당자의 Inbox에서 Primary 아래에 표시된다. 세 가지를 순서대로 읽어라. 1단계의 승인 기준, Agent가 실행한 검사와 아직 불확실한 부분을 나열한 Agent의 댓글, 그리고 실행 로그다. 그런 다음에야 diff를 본다.

별도의 테스트 Task가 변경을 검증한다면 그 관계를 명시적으로 기록하라. 조직 Owner와 Admin은 사용자 정의 링크 유형을 만들 수 있으며, 문서 자체의 예시인 validates / is validated by가 이 단계의 추적 가능성 연결선이다. 관계는 스스로 상태를 바꾸지 않으므로, 승인은 여전히 사람이 수행하는 상태 변경이어야 한다.

여기서 한 가지 범주 규칙이 보호해 준다. Task를 Completed로 옮기면 종료 상태로 표시되지만 이미 활성화된 실행을 취소하지는 않는다. Agent가 아직 작업 중이라면 먼저 취소하고, 그다음에 결정하라.

체인이 끊어지는 지점

위 워크플로에는 세 가지 알려진 단절 지점이 있으며, 이를 분명히 짚을 가치가 있다.

채팅에 남겨진 결론. 독립형 Agent Chat 세션은 이를 만든 사람에게 속한다. 설계가 그곳에서 확정되었다면 Task는 그것을 알지 못한다.

Task 외부에서 시작된 실행. 자동화 워크플로의 Run Agent 작업은 Task를 생성하지 않으며, 실행은 Agent에 기록된다. 야간 점검에는 괜찮지만, 기능 개발에는 적합하지 않다.

기록 대신 파일. Spec Kit의 spec.md, plan.md, tasks.md는 저장소 하나에서 작업하는 개발자 한 명에게는 강력한 체인이다. 팀이 곧 자신이라면 이것들을 사용하라. 두 번째 사람이 당신의 체크아웃을 열지 않고도 검토하거나, 승인하거나, 무슨 일이 있었는지 물어봐야 한다면 공유 작업 시스템을 사용하라. Sharkly는 Claude Code, Codex 또는 다른 실행 도구를 대체하는 것이 아니라, 그 도구들 주위에서 체인을 가시적으로 유지해 주는 계층이다. 각 개념에 대한 더 자세한 내용은 docs.sharkly.ai 문서에서 다룬다.

FAQ

요구사항에서 코드로 이어진다는 것은 Agent가 요구사항을 작성한다는 뜻인가? 아니다. 요구사항과 그 승인 기준은 사람이 작성한다. Agent는 코드베이스를 조사하고 Plan 모드에서 분해안을 제안할 수 있지만, 그 제안은 사람이 확인한 뒤에야 Task가 된다.

요구사항을 Jira에 두고도 추적 기록을 얻을 수 있나? 그렇다. Jira 가져오기와 동기화는 조직이 읽는 트래커를 유지하면서 Sharkly가 실행 기록을 보관한다. 인간-에이전트 팀을 위한 Jira 대안 글에서는 트래커 자체를 교체하려는 경우를 다룬다.

리뷰 전에 풀 리퀘스트가 병합되면 어떻게 되나? Task 상태는 바뀌지 않으므로, 체인에는 변경이 병합되었지만 승인되지 않은 Task가 표시된다. 그것이 올바른 신호다. 아직 사람이 내려야 할 결정이 남아 있다는 뜻이다.

첫 번째 추적 가능한 기능은 얼마나 작아야 하나? 요구사항 하나, 하위 태스크 두세 개, Agent 하나면 된다. Claude Code 프로젝트 관리 워크스루에서는 단일 Task로 이 루프를 처음부터 끝까지 실행한다.