개선 여정 설계

작성일: 2026-08-18 상태: 사용자 방향 승인(/docs 여정 둘, 파일럿은 URP AI 리포트 위젯). 사이트 구조는 구현 완료, 파일럿은 시작 전

배경

사이트가 지금 보여주는 자취는 기능 001 하나뿐이고, 그 하나가 백지에서 시작한 신규제작이다. 그런데 5240lab의 실제 일은 대부분 신규제작이 아니다 — 이미 돌고 있는 시스템을 고치고 거기에 무언가를 더한다. 사용자가 이번에 명확히 한 것이 그것이다.

대표 사례가 kiwibox eGov4.2다. 전자정부 표준프레임워크 기반 인사·근태·급여 시스템으로 8개 부시스템이 운영 중이고, 그 저장소에는 이미 모듈 문서 510편과 DB 문서 1599편이 쌓여 있다. 모듈 문서에는 화면이 무엇을 하는지, 어느 메뉴에 걸려 있는지, 어떤 테이블과 모듈에 이어져 있는지, 언제 마지막으로 확인했는지가 머리말에 적혀 있다.

그 저장소의 spec-kit은 첫 줄에 스스로를 이렇게 규정한다 — "새 기능 개발이 아니라 기존 소스/DB를 분석해 지식 자료를 만드는 용도". 즉 코드에서 문서를 뽑는 역방향은 있는데, 문서에서 출발해 고치고 다시 문서로 닫는 순방향이 없다. 기획할 때 기존 문서를 활용하고, 구현을 거쳐, 매뉴얼 수정까지 한 줄로 이어지게 하고 싶다는 요청은 정확히 그 빈칸을 메우자는 것이다.

목표

• 기존 시스템을 고치고 더하는 일을 여정으로 규정한다 — 단계, 각 단계의 통과 조건, 그 단계가 남기는 것.
• 그 여정을 /docs에서 신규제작 여정과 나란히 보여, 둘의 차이 자체가 설명이 되게 한다.
• 매뉴얼 갱신을 배포에 딸린 검사가 아니라 통과하지 못하면 끝나지 않는 단계로 올린다.
• 규정을 글로만 두지 않는다. 실제 개선 건 하나를 이 여정으로 통과시키고 그 자취를 싣는다.

두 여정은 무엇이 다른가

신규제작 7단계 앞에 둘(현행 확인, 영향 분석)이 붙고 뒤에 하나(문서·매뉴얼 갱신)가 정식 단계로 승격된다. 가운데 넷(기술 설계·작업 분해·구현·검증)은 그대로 쓴다 — 같은 일을 다른 이름으로 두 벌 만들지 않는다.

개선 여정 9단계

1. 현행 확인

통과 조건: 바꾸려는 화면의 모듈 문서가 있고, 그 문서의 마지막 확인일이 아직 유효하다. 없거나 낡았으면 여기서 멈추고 문서부터 만든다.

기존 문서 없이 시작하는 개선은 개선이 아니라 추측이다. 이 게이트가 그것을 막는다. 문서가 없을 때 되돌아갈 곳이 이미 있다 — kiwibox의 역방향 문서화 스킬이 그 일을 한다.

2. 개선 정의

통과 조건: 고칠 것과 더할 것이 기존 문서의 절 번호로 지목된다. "이 화면을 개선한다"가 아니라 "이 문서의 A3 항목 정의에서 이것을 이렇게 바꾸고, A5 뒤에 이것을 더한다"여야 한다.

지목이 안 되면 두 가지 중 하나다. 문서가 현행을 제대로 담고 있지 않거나(1단계로 돌아간다), 개선안이 아직 생각이 아니라 기분이다. 어느 쪽이든 진행할 때가 아니다. kiwibox 헌법의 "추정 금지, 출처 기재, 불확실은 미확인으로 표시"가 여기에 그대로 걸린다.

3. 영향 분석

통과 조건: 영향받는 모듈·테이블·메뉴·권한이 목록으로 뽑히고, 각 항목에 "확인함 / 영향 없음 / 확인 필요"가 붙는다.

추측으로 세는 것이 아니다. 모듈 문서 머리말에 이미 관련 모듈, 관련 테이블, 메뉴 코드, 권한 그룹이 적혀 있으므로 그 연결을 타고 넓힌다. 문서가 이 일을 하라고 그 필드를 갖고 있다 — 지금까지 챗봇이 읽는 용도로만 쓰였을 뿐이다.

4. 기술 설계

통과 조건: 기존 동작을 깨지 않는 방법이 설계에 적힌다. 데이터 이관이 필요하면 되돌리는 방법도 함께 적는다.

5. 작업 분해

통과 조건: 작업마다 되돌리는 방법이 있다.

6. 구현

통과 조건: 선언한 범위 밖 파일을 건드리지 않는다.

7. 검증

통과 조건: 새 동작과 기존 동작 불변이 둘 다 통과한다. 3단계에서 "확인 필요"로 남긴 항목이 하나도 남아 있지 않다.

신규제작의 검증은 "만든 것이 도는가"만 물으면 되지만, 개선의 검증은 "건드리지 않은 것이 그대로인가"를 함께 물어야 한다. 3단계 목록이 여기서 채점표가 된다.

8. 문서·매뉴얼 갱신

통과 조건: 매뉴얼 영향이 yes 또는 none으로 판정되고, yes면 실제 문서 변경과 마지막 확인일 갱신이 있다. none은 영향받는 독자·절차·공개 계약이 없다는 구체적 이유가 있을 때만 허용한다.

이 사이트가 이미 쓰고 있는 매뉴얼 게이트를 개선 여정에서는 독립 단계로 올린다. 2단계에서 "문서의 어느 절을 고칠지" 지목했으므로, 여기서 채점할 대상은 이미 정해져 있다 — 2단계가 약속이고 8단계가 이행이다. 둘이 맞지 않으면 통과하지 못한다.

9. 배포·운영

통과 조건: 배포 기록과 되돌아갈 기준점이 남는다.

사이트에 얹는 방법

/docs를 여정 둘로 확장한다. 공개 경로는 다섯 개 그대로이므로 헌법의 경로 조항을 건드리지 않는다.

검토한 다른 방향은 둘이었다. 개선 전용 경로를 새로 내는 안은 헌법의 다섯 경로 조항을 여섯으로 개정해야 하고 /docs와 내용이 갈라져 같은 말을 두 곳에서 관리하게 된다. /guide에 절만 더하는 안은 가장 싸지만 실제 자취와 연결되지 않아 설명에 머문다 — 이 사이트가 스스로에게 건 규칙("서류함이 아니라 자취를 보여준다")에 어긋난다.

데이터 구조

지금 content/journey.ts는 여정 하나를 내보낸다. 그 파일은 이미 "한 문서가 여러 여정·단계에서 다른 역할로 다시 나타날 수 있다"는 전제로 쓰여 있으므로, 여정을 복수로 만드는 것은 구조 변경이 아니라 예정된 확장이다.

• 여정 하나를 내보내던 자리를 여정 목록으로 바꾼다. 각 여정은 식별자, 이름, 한 줄 설명, 단계 배열을 갖는다.
• 단계 정의(gate, docs, actors)는 지금 모양 그대로 쓴다.
• 화면은 여정을 고르는 자리를 위에 두고 그 아래에 고른 여정의 단계를 펼친다. JavaScript 없이 읽혀야 하므로 선택은 링크로 만든다.

개선 여정의 문서를 어떻게 보여줄 것인가

여기에 제약이 하나 있다. /docs는 이 저장소 안의 파일만 스냅샷한다. kiwibox 문서를 그대로 실으려면 파이프라인을 사내 저장소까지 넓혀야 하는데, 모듈 문서에는 메뉴 코드·권한 그룹·테이블명 같은 내부 정보가 들어 있다.

이미 답이 있다. /5240lab의 근거 파이프라인은 이웃 저장소의 지정한 행 범위만 발췌해 공개 안전성을 검사한 뒤 싣는다. 개선 여정도 같은 방식을 쓴다 — 문서 전문이 아니라 "이 게이트를 실제로 통과했다는 근거 몇 줄"만 올린다. 공개 범위 문제가 사라지고 기존 규율과 같은 결이 된다.

따라서 개선 여정의 단계는 문서 전문 링크 대신 다음 셋을 잇는다.

1. 그 단계의 통과 조건
2. 통과했다는 근거 발췌(검증된 공개 스냅샷에서)
3. 그 단계를 설명하는 가이드 대목

파일럿

kiwibox의 URP AI 리포트 어시스턴트 위젯 작업을 이 여정으로 통과시킨다. 사이트에 싣기 전에 실제로 한 번 돌려야 한다 — 그래야 설명이 아니라 자취가 된다. 기능 001이 그랬다.

이 건은 1단계 재료가 이미 있다. AI 위젯이 실제로 연결된 화면과 각 화면이 백엔드를 호출하는 방식을 정리한 문서가 있고, 코드 검증 기준일이 적혀 있으며, 관련 모듈 넷이 머리말에 선언돼 있다. 즉 현행 확인이 끝난 상태에서 2단계부터 시작할 수 있다.

비목표

• kiwibox 저장소의 spec-kit 스킬을 고치지 않는다. 개선 여정은 그 스킬들을 어느 단계에 쓰는지 규정할 뿐이고, 스킬 자체의 변경은 별개 작업이다.
• kiwibox 모듈 문서 전문을 공개하지 않는다.
• 신규제작 여정의 단계 정의를 바꾸지 않는다.
• 여정을 셋 이상으로 일반화하지 않는다. 둘을 제대로 보여준 뒤에 필요하면 넓힌다.

검증

• 여정 둘이 각각 단계·게이트·근거를 갖추고, JavaScript 없이 읽힌다.
• 여정을 고르는 링크가 키보드로 닿고, 다섯 폭에서 가로 넘침이 없다.
• 개선 여정이 참조하는 근거 식별자가 실재하는지 빌드 시점에 검사한다. 없는 것을 가리키면 빌드가 멈춰야 한다.
• 파일럿이 8단계를 실제로 통과했다는 근거가 있을 때까지 그 단계를 완료로 표시하지 않는다.

열린 것

• 파일럿의 2단계(개선 정의)가 지목할 대상 문서와 절을 아직 정하지 않았다.
• 개선 여정의 근거를 어느 저장소 파일에서 뽑을지, 공개 안전 검사에 걸리는 대목이 있는지 확인하지 않았다.
• 여정 식별자를 화면에 노출할지 정하지 않았다. 신규제작 여정은 기능 번호를 화면에서 뺐다 — 읽는 사람에게 필요한 것은 "어느 기능이었나"가 아니기 때문이다. 같은 판단을 개선 여정에도 적용할지는 파일럿을 실을 때 정한다.