Jira에 결정 로그 남기기: 이 방식을 선택한 이유를 기억하세요

출시 6주 후 누군가 일일 요약 대신 이메일을 선택한 이유를 묻습니다. Jira 티켓에는 만든 내용이 있고 댓글에는 '계획 때 합의'라고 적혀 있습니다. 대화를 기억하는 사람은 바쁘고 어떤 제약이 가장 중요했는지 확실하지 않습니다.

결정 로그는 이 틈을 채웁니다. 상황, 대안, 선택, 결과를 찾기 쉬운 곳에 남깁니다. Power Pack의 Decision Log에서는 설명하는 작업 가까이, Jira 이슈 옆에 기록을 둡니다.

이 안내는 가상 포털 팀이 유용한 기록을 작성하고 구현과 연결하며 고객 요구가 달라졌을 때 다시 검토하는 과정을 보여줍니다.

기록할 만한 결정을 정하세요

모든 대화를 기록할 필요는 없습니다. 미래 동료가 합리적으로 질문할 선택부터 시작하세요. 구현 방식, 의존성, 출시 범위, 작은 작업을 넘어 영향을 주는 의도적 절충 등이 해당합니다.

포털 팀의 알림 방식은 기록할 가치가 있습니다. 즉시 이메일 선택은 구현, 테스트, 지원 안내, 고객 기대에 영향을 줍니다. 팀은 대안을 검토했고 메시지가 늘면 다시 살펴볼 계획입니다.

반면 버튼 오타 수정은 별도 기록이 필요하지 않을 수 있습니다. 이유를 이해하는 것이 나중에 유지, 변경, 설명에 도움이 되는지가 실용적인 기준입니다.

ADR이라고 부르는 아키텍처 결정 기록은 좋은 선례입니다. Michael Nygard의 원문은 맥락, 결정, 상태, 결과를 짧게 기록하고 대체된 결정은 새 결정 참조와 함께 보존하는 방식을 설명합니다. 출처는 아래에 있습니다. 여기서는 이 가벼운 방식을 Jira 구현 결정에 적용합니다.

결정이 있을 위치를 명확히 하세요

선택의 영향을 가장 잘 대표하는 이슈를 고르세요. 예시에서는 포털 알림을 조율하는 이슈를 사용하며 이미 개발과 테스트를 안내하고 있습니다.

기록 위치를 팀에 알리세요. Decision Log는 이슈에 속하므로 찾는 습관을 정해야 합니다. 조율 이슈에 알림 결정은 여기에서 관리한다고 적을 수 있습니다. 별도 프로젝트 색인이 있다면 정상 절차로 이슈를 추가하세요.

여러 이슈에 복사본을 흩뿌리고 일치하기를 기대하지 마세요. 다른 티켓은 원래 위치를 안내하면 됩니다. 내보낸 사본은 논의에 유용하지만 현재 입장을 확인할 기록은 분명해야 합니다.

결론보다 맥락을 먼저 쓰세요

맥락은 질문이 생긴 이유입니다. 사실, 제약, 가정을 구분해 미래 독자가 무엇이 변했는지 알게 하세요.

팀은 이렇게 씁니다. '지원 요청이 의미 있게 바뀌면 고객이 알아야 한다. 현재 서비스는 이미 이메일을 보낸다. 포털 첫 버전에는 받은편지함이 없다. 대부분 요청의 고객 공개 상태 변경은 적을 것으로 예상하지만 출시 후 알림량은 아직 측정하지 않았다.'

이는 '이메일이 가장 간단하다'보다 유용합니다. 출발점과 가정을 밝히며 이메일이 항상 옳다고 주장하지 않습니다.

필요하면 조사 참조를 추가하세요. 기술 검토가 선택에 영향을 줬다면 결과가 있는 Jira 이슈를 지정합니다. 고객 피드백이 중요하면 개인정보를 불필요하게 옮기지 말고 관련 경향을 요약하세요.

새 동료가 회의 전체를 복원하지 않고 상황을 이해할 수 있어야 합니다. 선택에 영향을 주는 세부사항은 남기고 무관한 대화는 원래 위치에 두세요.

실제 대안을 비교하세요

유용한 기록은 팀이 달리 할 수 있었던 것을 보여줍니다. 진지하게 고려한 대안마다 정직한 장단점을 적으세요.

이 평가는 가상 시스템에 대한 예시입니다. 다른 팀에는 이미 받은편지함이나 요약 서비스가 있어 비교가 완전히 달라질 수 있습니다. 좋은 기록은 맥락에 대한 의존성을 드러냅니다.

선택한 안이 필연처럼 보이도록 탈락한 대안을 깎아내리지 마세요. 요약은 개별 메시지를 줄이는 실제 장점이 있습니다. 지금은 시점과 구현 범위가 더 중요해 이번 출시에서 제외한 것입니다.

대안과 별도 결정도 구분하세요. 고객 메시지 전체를 이메일에 넣을지는 별도 검토가 필요할 수 있습니다. 모든 알림 질문을 한 기록에 넣으면 실제 합의를 이해하기 어렵습니다.

선택과 결과를 명시하세요

완전한 문장으로 쓰세요. '포털 첫 버전에서는 지원 요청에 의미 있는 고객 공개 상태 변경이 생기면 이메일을 보낸다. 내부 편집은 메시지를 발생시키지 않는다.'

이유도 적습니다. '기존 전달 채널로 고객에게 빠르게 알리면서 출시 범위를 관리할 수 있다.' 이는 이 사례의 근거이지 이메일이 언제나 저렴하거나 안정적이라는 주장이 아닙니다.

결과에도 같은 주의가 필요합니다. 의미 있는 변경의 공통 정의, 반복 업데이트와 중복 처리 테스트, 발송 사건을 설명할 지원 준비가 필요합니다. 활동이 많은 고객은 여전히 원치 않는 만큼 이메일을 받을 수 있습니다.

유용한 결과는 후속 작업으로 이어집니다. 영향은 여기 기록하고 작업은 Jira에서 관리하세요. 결정 기록은 필요성을 설명해야지 상태와 담당자가 경쟁하는 두 번째 백로그가 되어서는 안 됩니다.

Power Pack에 기록을 만드세요

관련 이슈에서 Decision Log (ADR Lite)를 열고 '일반 포털 상태 업데이트에 즉시 이메일 사용'처럼 실제 선택을 나타내는 제목으로 항목을 추가합니다.

팀에 맞는 범주를 고르고 논의 중에는 Proposed로 시작하세요. 결정자와 결정 후 날짜를 넣습니다. 결정자 필드는 책임을 기록할 뿐 이름 입력이 승인 절차를 수행하지 않습니다.

맥락, 대안의 장단점, 선택한 항목, 결과를 작성하세요. 대화에 없었던 사람도 이해할 수 있게 합니다.

필요한 Jira 키를 추가하세요. 편집기는 쉼표로 구분한 참조를 받아 영향받는 개발·테스트 티켓을 표시할 수 있습니다. 이는 기록된 참조이며 이슈 관계가 필요하면 Jira의 일반 연결 절차를 별도로 사용하세요.

참여자와 완성 기록을 검토하고 선택과 설명이 맞는지 확인하세요. 동료가 최신 버전에 의존하기 전에 저장 상태를 확인하며 특히 로컬·오프라인 표시에 주의하세요.

상태로 현재 입장을 분명히 하세요

Power Pack에는 Proposed, Accepted, Rejected, Superseded가 있습니다. 아직 검토 중인 생각과 구현을 이끄는 결정을 구분할 수 있도록 사용법을 합의하세요.

Maya가 알림 방식을 정하면 날짜를 기록하고 Accepted로 표시합니다. 이는 결정의 입장이지 구현 완료, 테스트 통과, 출시 허가를 증명하지 않습니다.

Rejected도 같습니다. 채택하지 않은 이유를 짧게 남기면 다음 사람이 이전 조사를 모르고 반복하는 일을 줄일 수 있습니다. 구현 티켓이 생기지 않아도 유용한 근거는 보존하세요.

가정이 달라지면 결정을 재검토하세요

출시 후 활성 요청이 많은 고객이 들어온다고 가정해 보세요. 지원팀은 일부 고객이 매일 여러 일반 이메일을 받는다고 보고합니다. 적은 메시지량이라는 원래 가정과 직접 연결된 새로운 맥락입니다.

변경 제안 전에 옛 기록을 열면 당시의 합리적인 절충과 오늘의 질문을 구분할 수 있습니다. 기존 결정은 즉시 이메일의 이유를 설명하지 다른 조건에서 더 나은 접근을 금지하지 않습니다.

일일 요약에 대한 새 Proposed 항목을 만드세요. 기존 항목을 Proposed로 복제해 시작할 수 있습니다. 복사된 가정, 날짜, 결과는 더 이상 맞지 않을 수 있으므로 모든 필드를 확인하세요.

새 선택이 채택되면 기존 기록을 Superseded로 바꾸고 대체 필드에 새 결정을 참조하세요. 처음부터 요약을 의도했던 것처럼 고치지 말고 원래 이유를 읽을 수 있게 남깁니다.

이는 팀의 문서화 관행입니다. 항목은 수정 가능하므로 중요한 변경에는 대체 기록을 만들고 일반 편집은 정정·설명에 쓰기로 합의하세요. 불변 감사 기록으로 취급하지 마세요.

일상 업무에서 활용하세요

새 동료가 합류하거나 재설계를 제안하거나 특이한 요구사항의 이유를 물을 때 보세요. 검색과 필터로 이슈 로그의 항목을 찾을 수 있고, ADR 형식 Markdown으로 내보내 다른 검토·문서 과정에 사용할 수도 있습니다.

내보낸 파일이 현재 내용을 반영하는지 확인하고 관리하는 Jira 이슈를 안내하세요. 다운로드는 스냅샷이므로 나중 편집이 이미 보낸 사본을 갱신하지 않습니다.

최근 결정 중 재검토 가능성이 있는 하나로 시작하세요. 맥락, 진짜 대안, 선택, 결과를 작업 옆에 기록하고 회의에 없었던 동료에게 읽게 하세요. 당시 선택이 타당한 이유와 바꿀 조건을 설명할 수 있다면 로그가 제 역할을 하는 것입니다.

• Michael Nygard: 아키텍처 결정 문서화