artifact-transformer 작업 일지 #27

이 글은 2026-07-15 하루의 기록이다. #26에서 뷰어를 편집기로 바꿨다면, 이날은 그 편집기가 놓일 자리 자체를 다시 그렸다 — 산출물 관리 도구에서 SW 개발 전주기 플랫폼으로. 오전엔 “요구사항을 Jira로 옮길 것인가”를 놓고 데스크톱 Agent Mode에서 설계 문답만 했고, 오후엔 Task를 Story로 바꿨다가 두 시간 만에 Task로 되돌렸다. 그 왕복이 이날 배운 것의 전부다.

배경 — 도구의 경계를 넓히기로 했다

artifact-transformer는 31종 산출물을 생성·검증하는 CLI에서 출발해, 인증(#25)과 편집·영향성 검토 게이트(#26)를 거치며 웹 서비스가 됐다. 이날의 요청은 그 경계를 다시 그리는 것이었다.

산출물 관리 도구에서 SW 개발 전주기를 관리하는 플랫폼으로 확장하고자 해. 우선 좌측 메뉴를 SW 개발 전주기를 위한 단계별로 변경하고, 각 단계별 화면을 개선해줘. 상단에 산출물·식별자·정합성·발행 기능을 각 단계별 화면에 녹여줘.

지금까지 좌측 메뉴는 산출물 목록이었다. 즉 도구가 사용자에게 보여 주던 세계는 “네가 만들어야 할 문서들”이었다. 이걸 단계(업무 정의 → 분석 → 설계 → 구현 → 시험 → 인도)로 바꾸면 세계가 달라진다 — “네가 지금 어느 단계에 있고, 여기서 무엇을 해야 하는가”. 산출물은 그 단계의 결과물로 격하된다.

메뉴 하나 바꾸는 일이 아니라, 제품이 무엇인지에 대한 답을 바꾸는 일이었다.

문제

1. 모든 데이터를 Jira 이슈로 관리하는 게 맞나. 산출물(docx·md)은 두고 JSON 데이터만 이슈 유형별로 만든다면?
2. 요구사항 충족 여부를 산출물에서 관리하나, Jira에서 관리하나. 지금은 1:1 맵핑이다.
3. 맵핑을 걷어내면 요구사항의 계층(classification·categories·subCategories)은 어디로 가나.
4. 업무 정의 작업을 Jira에 올릴 때 Story인가 Task인가.
5. 에픽 추천 같은 AI 보조는 언제 자동으로 걸려야 하나.
6. 작업·데이터·이력·산출물은 화면에서 어떤 관계여야 하나.

결정 1 — 요구사항의 정본은 산출물, Jira는 작업만

오전은 코드를 한 줄도 안 쓰고 설계 문답만 했다. 시작은 이 질문이었다 — “모든 데이터를 Jira의 이슈로 관리하는 것 어떻게 생각해? 물론 docx·md 같은 산출물은 기존처럼 유지하되, JSON 데이터를 이슈 유형별로 생성하는 방안.”

매력적인 안이다. Jira가 이미 계층(에픽 → 스토리 → 서브태스크)·상태·링크·검색을 다 갖고 있으니, 요구사항을 이슈로 만들면 그 기능을 공짜로 얻는다. 그런데 이 방향은 #25에서 정한 원칙과 정면으로 부딪친다 — 복제 대신 참조. Jira는 작업의 정본, 저장소는 내용의 정본.

요구사항을 이슈로 만든다는 건 곧 내용의 정본을 둘로 쪼갠다는 뜻이다. requirements.json에도 있고 SULAS-XXXX에도 있는 순간, 둘은 반드시 어긋난다. 그리고 이 제품의 존재 이유가 바로 “산출물끼리 어긋나지 않게 하는 것”이다. 자기가 푸는 문제를 스스로 만들 이유가 없다.

그래서 다음 질문으로 좁혔다 — “요구사항에 대한 충족 여부를 산출물에서 관리하는 게 좋을까, Jira에서 관리하는 게 좋을까? 현재는 1:1 맵핑을 통해 관리하고 있어.” 그리고 더 날카롭게 — “Jira와 요구사항 맵핑을 제거하고, Task 관리만 연동하는 게 바람직한가?”

정리한 답은 이렇다.

요구사항 1:1 맵핑은 걷어낸다. 요구사항 하나가 생길 때마다 이슈 하나가 생기는 구조는, 추적성을 얻는 대신 두 시스템을 영원히 동기화해야 하는 부채를 진다. 요구사항은 산출물 안에서 식별자로 추적하면 되고 — 이미 「SW 산출물 식별자 정책」이 그 일을 한다 — Jira는 사람이 하는 일만 들고 있으면 된다.

결정 2 — 계층은 따라가지 않는다

맵핑을 걷어내자 곧바로 걸린 게 있었다. “요구사항의 계층(classification, categories, subCategories)을 Jira의 계층에 투영하고 요구사항 기반으로 Task를 생성하여 추적성을 관리하고 있었는데, 요구사항 맵핑을 제거하면 계층은 어떻게 해?”

이게 이날 오전의 진짜 문제였다. 지금까지는 요구사항의 3단 분류를 Jira의 에픽·스토리 계층에 그대로 겹쳐 놨다. 맵핑이 사라지면 그 투영도 무너진다.

결론은 투영을 복원하지 않는 것이었다. 두 계층은 애초에 같은 것을 나누는 축이 아니다.

• 요구사항 계층은 내용의 분류다 — 이 요구사항이 어느 도메인·기능군에 속하는가. 산출물 안에서만 의미가 있고, 식별자 체계(SDSP-REQ-GEO-API)가 이미 그것을 담고 있다.
• Jira 계층은 일의 분류다 — 이 작업이 어느 목표에 기여하는가. 에픽은 요구사항 분류가 아니라 프로젝트의 진행 단위다.

둘을 억지로 포갠 게 원래의 실수였다. 요구사항 분류가 100개면 에픽이 100개가 되는데, 그건 아무도 쓰지 않는 에픽 100개다. 그래서 계층은 산출물 쪽에 남기고, Jira에는 사람이 실제로 관리하는 소수의 에픽만 둔다. 작업은 요구사항에서 자동 파생되는 게 아니라 사람이 정의하고, 에픽에 붙는다.

두 시스템에 같은 계층을 그리면 추적성을 얻은 것 같지만, 실제로 얻는 건 동기화 작업이다.

결정 3 — Story로 갔다가 Task로 돌아왔다

오후는 왕복이었다. 순서대로 적는 게 정직할 것 같다.

14:18 — Story로 간다. “Task 생성 → Story 생성으로 변경하고, Story를 [Confluence 가이드]대로 생성해줘. Jira Story 생성 가이드는 Skills에 기록해줘. Story 생성 시 Story point 등 필요한 정보들을 제안하고, 수락하면 실제 이슈를 생성할 수 있는 흐름으로.”

14:28 — 오해 정정. “이전에 Task를 Story 형태로 생성하고자 했던 거야. 업무 정의 자체를 Story로 변경하는 게 아니라.” 이슈 유형을 바꾸라는 게 아니라 문안 품질을 Story 수준으로 올리라는 뜻이었다.

14:40 — Story 문법을 스킬에 박는다. Atlassian의 사용자 스토리 문법을 그대로 규약으로 넣었다.

“저는 [페르소나]로서, [하고 싶은 일]을 하여 [목적]을 이루고 싶습니다.”

가이드의 핵심은 세 가지였다. 페르소나는 직책이 아니라 팀이 공동으로 이해하는 한 사람이다. 하고 싶은 일은 기능이 아니라 의도이며, UI를 설명하고 있다면 논점을 놓친 것이다. 목적은 그 즉각적 바람이 더 큰 그림에 어떻게 맞는가다.

16:11 — 되돌린다. “구현을 제외하고 모두 Task 생성으로 다시 변경. 단 Task에도 Points 유지(Story points → points).”

16:35 — 왜 되돌렸는지가 드러난다. “Task는 Story와 문안 형식이 다름. Task에 적합한 구조로 변경해줘.”

여기서 배운 게 이날의 핵심이다. Story 문법을 실제 작업 목록에 적용해 보니 거짓말이 됐다. 업무 정의 단계의 작업 목록은 이런 것들이다 — “업무 범위·목록 도출 1차”, “이해관계자 식별·정의”, “RACI 확정”, “업무 구성도(BCDG) 작성·동기화”. 여기에 페르소나 문장을 씌우면 이렇게 된다: “저는 분석가로서, RACI를 확정하여 책임 소재를 명확히 하고 싶습니다.”

문법은 맞지만 아무것도 더해 주지 않는다. 페르소나 문법은 사용자 가치를 포착하기 위한 문법이고, 그 가치가 실재할 때만 작동한다. 산출물을 작성하는 내부 작업에는 포착할 사용자 가치가 없다 — RACI 확정은 누구의 삶도 나아지게 하지 않고, 그냥 해야 하는 일이다. 억지로 페르소나를 세우면 문장만 길어지고 정보는 줄어든다.

그래서 유형을 갈랐다. 구현 작업은 Story(실제 사용자 가치가 있으므로 페르소나 문법이 정보를 더한다), 그 외 전부는 Task(명령형이 정직하다). Points는 두 쪽 다 남겼다 — 복잡도 추정은 사용자 가치와 무관하게 필요하니까.

Task의 문안 규약은 이렇게 못 박았다.

문안 형식 (Task — 명령형·기술 설명. 페르소나 문장 금지):
- summary: 명령형 한 줄 (예: "업무 분류 체계 정비")
- detail:  무엇을 하는지 (명령형, 여러 줄 가능)
- purpose: 왜 필요한지 한 줄
- done:    완료 조건 2~3개 — 체크 가능하게 ("모호"·"적절히" 금지)
- points:  1·2·3·5·8 중 하나 (복잡도·규모)
- reason:  이 제안의 근거 (문서의 어느 부분에서 보였는지, 30자 내외)

done의 괄호가 이 규약의 핵심이다. “적절히 정리한다”는 완료 조건이 아니다. 체크할 수 없으면 완료 조건이 아니다.

문안 형식이 맞지 않는다는 건 글쓰기 문제가 아니라, 이슈 유형을 잘못 골랐다는 신호였다.

결정 4 — 에픽은 고르게 하고, AI는 추천만

Task 생성이 400 에러로 막혔다. 원인은 단순했다 — 이 프로젝트의 Jira는 상위 에픽 없이는 이슈를 못 만들게 되어 있다. 요청은 “상위 에픽을 선택할 수 있게 해줘. Task 제안 시 LLM으로 추천도 해줘”였다.

여기서 중요한 건 선택과 추천을 가른 것이다. 결정은 사람이 하고, AI는 후보를 올린다. 그리고 추천 프롬프트에 #25의 오탐 방지 원칙을 그대로 넣었다.

규칙:
- **주어진 에픽 중에서만** 고른다. 새 에픽을 지어내지 않는다.
- 작업의 실질 목적이 에픽의 주제와 맞물리는 것을 고른다
  (요약어 단어 일치가 아니라 실무로).
- 마땅한 에픽이 없으면 그 작업은 결과에서 **뺀다** (억지로 배정하지 않는다).
- reason 은 한 줄(30자 내외)로 근거만.

“마땅한 에픽이 없으면 뺀다”가 이 프롬프트의 절반이다. LLM에 목록과 항목을 주고 매핑하라고 하면 반드시 전부 매핑한다 — 빈칸을 남기는 걸 실패로 여기기 때문이다. 그런데 잘못 배정된 에픽은 배정 안 된 것보다 나쁘다. 사람이 “이건 검토됐다”고 믿고 넘어가니까. 자동화의 적은 못 하는 게 아니라 틀린 걸 그럴듯하게 해내는 것이다.

작업 제안 프롬프트에도 같은 장치를 걸었다.

문서의 실제 내용에서 근거가 보이는 것만 (빠진 정보·불일치·후속 정리 등). 일반론(“품질을 높인다”)이나 근거 없는 추측은 금지. 이미 계획된 작업과 겹치면 제안하지 않는다. 제안할 것이 없으면 빈 배열. 억지로 채우지 마라. 최대 5개.

결정 5 — 자동 실행의 경계는 이미 LLM인가로 가른다

AI 보조를 언제 자동으로 걸지가 오후 내내 미세 조정 대상이었다. 흐름이 이렇게 정리됐다.

처음엔 “작업 제안” 버튼 하나였다. 여기에 “추가 제안”을 붙였다 — 기본 업무 제안이 표준 목록이라면, 추가 제안은 LLM이 문서를 읽고 더 필요한 걸 찾아내는 것. 그러자 에픽 추천이 어디에 붙어야 하는지가 문제가 됐다.

한 번 잘못 걸렀다. “추가 제안 시 기본적으로 에픽 추천을 실행하지 말고, 에픽 추천 버튼 클릭 시 맵핑”이라고 했더니 반대로 이해했고, 정정이 들어왔다 — “AI가 추가 제안 뒤에 자동으로 걸리던 suggestEpics는 유지하고, ‘작업 제안’으로 표준 작업 호출 시 suggestEpics를 제거해 달라는 거였어.”

정정을 받고 나니 기준이 명확해졌다. 이미 LLM 경로면 자동, 결정적 경로면 수동.

표준 작업은 결정적이다 — 목록이 고정이고, 어느 에픽에 붙을지도 사람이 이미 안다. 여기에 LLM을 걸면 비용과 지연만 생긴다. 반면 AI 추가 제안은 이미 LLM을 호출한 참이고, 제안된 작업이 어느 에픽에 속하는지도 모르는 상태다. 거기선 추천이 값을 한다.

#26에서 정한 “결정적 코어 + 최소 AI”가 이번엔 UI 흐름으로 내려왔다. 편집 흐름에도 같은 결로 “AI 편집” 버튼을 따로 뒀다 — 편집은 기본이 손이고, AI는 명시적으로 부를 때만 온다.

결정 6 — 작업을 데이터의 부속물에서 꺼냈다

저녁은 정보 구조와의 싸움이었다. 발단은 “작업 계획을 IntelliJ의 Task처럼 적용하고 싶어”였다. IntelliJ의 Task는 이슈를 열면 브랜치·컨텍스트가 따라오는 것 — 작업이 IDE의 일급 개념이라는 뜻이다.

처음엔 작업 계획을 데이터 화면 안에 넣었다. 그러자 곧 걸렸다. “작업 계획은 데이터 레이아웃이 아닌 공통으로 적용되어야 할 것 같아.” 그리고 확정 — “작업 계획을 데이터·이력·산출물과 같은 레벨로 올려줘. 명칭을 작업으로.”

작업 계획이 데이터 탭 안에 있으면 그건 데이터의 부속물이다. 하지만 작업은 데이터에 딸린 게 아니라 데이터·이력·산출물과 나란한 축이다. 탭을 한 단계 올리는 건 픽셀 문제가 아니라, 사용자가 이 도구를 어떻게 이해하는가의 문제다. 이름도 “작업 계획”에서 **“작업”**으로 줄였다 — 계획만이 아니라 진행·완료를 다 담으니까.

같은 결로 나머지도 정리했다.

• 데이터 하위의 문서 정보 → 산출물 탭으로. 문서 정보는 데이터의 속성이 아니라 산출물의 속성이다.
• 현황 상세·프로젝트 정보 → 화면 전환형으로. 늘 펼쳐 둘 게 아니라, 볼 때 화면을 넘겨 보는 것.
• 산출물·식별자·정합성·발행 → 검색·AI 지시와 같은 Bar의 오른쪽 끝으로. 작업·이력도 같은 자리로. 자주 안 건드리는 도구는 가장자리로 몬다는 #26의 원칙 연장이다.
• AI 지시 → 검색과 같은 Bar 우측에. “검색 이동처럼 텍스트를 바로 입력하거나, 단축키로 팝업창에서 여러 AI 지시를 할 수 있도록.” IntelliJ의 Search Everywhere를 AI 지시에 옮긴 셈이다.
• JSON 변환 기능 삭제. 편집기가 스키마 폼으로 다 되는데 원본 JSON을 손으로 변환하는 통로를 남겨 둘 이유가 없다. 게이트를 우회하는 뒷문이기도 했다.

탭의 위치는 취향이 아니다. 정보 구조가 곧 사용자의 사고 구조가 된다.

의도치 않은 함정 — 나가는 길을 안 만들었다

화면 전환형 UX로 바꾸다가 이날 가장 멍청한 버그를 만들었다. “관리 화면에서 프로젝트 화면으로 넘어갈 수가 없어.”

들어가는 길만 만들고 나오는 길을 안 만든 것이다. 전환형 UI의 고전적 실패다 — 한 화면을 다른 화면으로 덮는 방식이라, 덮은 화면에 복귀 경로가 없으면 사용자는 갇힌다. 탭이었을 땐 옆에 다른 탭이 늘 보였으니 이 문제가 없었는데, 전환형으로 바꾸는 순간 복귀는 명시적으로 만들어야 하는 것이 됐다.

Jira API 오류도 두 번 났다. 하나는 인증·필드 문제였고, 다른 하나가 앞서 적은 400 — 상위 에픽 필수 제약이었다. 둘 다 “우리 쪽 스키마”와 “저쪽 프로젝트 설정”이 다르다는 걸 실제로 던져 보기 전엔 몰랐다는 공통점이 있다.

한편 CLI 채널에서는 평소의 일이 흘렀다 — SUOMS-623, SUOMS-630, IAMS-157 이슈 처리. #26에서 만든 피드백 사이클이 이젠 별 얘깃거리 없이 도는 게 오히려 좋은 신호다.

마무리

이날은 왕복의 날이었다. Task → Story → Task, 자동 → 수동 → 조건부 자동. 그런데 왕복이 낭비는 아니었다. 되돌아온 자리는 출발점과 같아 보이지만, 이유를 알고 서 있다는 점이 다르다.

• 요구사항의 정본은 산출물, Jira는 작업만 — 1:1 맵핑을 걷어냈다. 내용을 두 시스템에 두면 얻는 건 추적성이 아니라 동기화 부채다. #25의 “복제 대신 참조”를 요구사항까지 밀었다.
• 계층은 투영하지 않는다 — 요구사항 계층은 내용의 분류, Jira 계층은 일의 분류. 다른 축을 포개면 아무도 안 쓰는 에픽 100개가 생긴다.
• 문안 형식이 이슈 유형을 결정한다 — 페르소나 문법은 사용자 가치가 실재할 때만 작동한다. 구현은 Story, 산출물 작업은 명령형 Task. Points는 양쪽 다.
• 완료 조건은 체크 가능해야 한다 — “적절히 정리한다”는 완료 조건이 아니다. 규약에 “모호·적절히 금지”를 박았다.
• 억지로 채우지 마라 — 에픽 추천은 마땅한 게 없으면 빼고, 작업 제안은 근거가 없으면 빈 배열. LLM은 빈칸을 실패로 여기므로 명시적으로 허락해 줘야 한다.
• 자동화 경계는 이미 LLM인가로 가른다 — 결정적 경로(표준 작업)엔 AI를 안 걸고, LLM 경로(추가 제안)엔 이어 붙인다.
• 작업은 일급 축이다 — 데이터의 부속 탭에서 꺼내 데이터·이력·산출물과 같은 레벨로.

다음에 남는 것:

• 요구사항 1:1 맵핑 제거의 실제 마이그레이션 — 기존에 만들어 둔 요구사항 파생 이슈들을 어떻게 정리할지.
• 좌측 메뉴 단계별 재편의 나머지 단계(분석·설계·구현·시험·인도) 화면. 이날 끝낸 건 업무 정의 하나다.
• 전환형 화면 전반의 복귀 경로 점검 — 관리 화면 하나에서 걸렸다면 다른 데도 있다.
• 에픽 추천의 오탐률을 실사용으로 확인. “억지로 배정하지 않는다”가 프롬프트에만 있고 실제로는 안 지켜질 수 있다.
• 구현 단계에서 Story 문법이 정말 값을 하는지 검증 — 이날 Task로 되돌린 근거가 “가치가 없으면 페르소나도 없다”였으니, 가치가 있는 쪽에선 반대가 성립해야 한다.