매뉴얼 단계를 여정별로 가르고 대상 매뉴얼을 명시하는 설계

작성일: 2026-08-19 상태: 사용자 승인(신규는 제작·SM은 동기화, 두 여정 모두 대상은 5240 통합 매뉴얼)

배경

사용자가 세 가지를 지적했다.

1. 「매뉴얼 동기화 게이트」 절이 「검사 실행」 절보다 앞에 있다. 순서가 뒤집혔다.
2. 매뉴얼 "동기화"는 SM에만 맞는 말이다. 신규제작은 없던 매뉴얼을 만드는 일이고, SM은 이미 있는 매뉴얼을 고치는 일이다.
3. SM의 매뉴얼 동기화 대상은 5240 통합 매뉴얼 사이트다. 지금은 무엇과 동기화하는지가 화면 어디에도 없다.

셋 다 타당하다. 특히 두 번째는 저장소가 이미 절반쯤 인정하고 있던 것이다 — 개선 여정의 그 단계에는 *"신규제작에서는 배포 단계에 딸린 검사이지만, 개선 여정에서는 통과하지 못하면 끝나지 않는 독립 단계"*라는 주석이 달려 있고, 공개 문서 화면의 신규제작 일곱 단계에는 매뉴얼 단계가 아예 없다. 그런데 작업 가이드의 신규제작 열 단계는 여덟 번째를 여전히 「매뉴얼 동기화」로 부른다. 한 사실을 두 화면이 다르게 말하는 자리가 또 하나 있던 셈이다.

세 번째는 더 깊은 결함이다. "동기화"는 두 대상이 있어야 성립하는 말인데 상대가 적혀 있지 않다. 읽는 사람은 무엇과 맞추라는 것인지 알 수 없고, 그 상태로는 게이트를 통과했는지 판정할 수도 없다. 브라우저 검사에 판정 기준이 없던 것과 같은 종류의 빈칸이다.

결정

단계 이름을 여정별로 가른다.

계층 이름(여덟 계층 중 하나)은 「매뉴얼 동기화」 그대로 둔다. 계층은 두 여정을 함께 덮는 규율이고, 갈리는 것은 그 규율이 각 여정에서 취하는 모양이다.

두 여정의 대상 매뉴얼을 하나로 명시한다. 신규제작이 만든 매뉴얼이 그대로 SM의 수정 대상이 된다. 한 자리를 가리켜야 "제작 → 갱신"이 끊기지 않고, 링크도 한 곳만 관리한다. 대상은 5240 통합 매뉴얼 사이트(https://guide.5240.cloud)다.

절 순서를 바꾼다. 검사 실행이 매뉴얼보다 앞에 온다. 코드가 통과했는지 먼저 판정하고, 그다음에 그 변경이 매뉴얼에 미친 영향을 닫는다. 지금 순서는 그 반대였다.

대상 매뉴얼을 화면에 박는 것에 대해

이 사이트는 일하는 방법을 팔지 특정 도구나 특정 사이트를 팔지 않는다. 그래서 「일을 끌고 가는 것들」의 세 층마다 "도구가 없다면 누가 그 자리를 맡는가"를 함께 적어 왔고, 게이트 문구에는 도구 이름을 넣지 않는다.

매뉴얼 대상은 다르다. 도구는 바꿔 끼울 수 있는 수단이지만, 동기화의 상대는 그 일의 대상 자체다. 상대가 없으면 문장이 성립하지 않는다. 다만 같은 관례는 지킨다 — 이것이 5240lab의 매뉴얼이라는 것을 밝히고, 다른 조직은 자기 매뉴얼이 그 자리에 온다고 함께 적는다. 그러면 읽는 사람이 "이 사이트를 쓰려면 저 사이트가 있어야 한다"로 오해하지 않는다.

범위

포함:

• content/harness.ts — 여덟 번째 단계 이름과 설명(신규제작 축)
• content/journey.ts — 개선 여정 그 단계의 라벨
• content/guide.ts — manualSyncGate에 대상 매뉴얼과 여정별 성격, guideSections 순서
• app/guide/page.tsx — 절 순서와 대상 매뉴얼 렌더
• lib/docs-safety.ts와 scripts/verify-manual.mjs — 외부 URL 허용 목록에 매뉴얼 사이트 추가
• 위 변경을 요구하는 단위·통합·브라우저 테스트

제외:

• 게이트 문구가 요구하는 내용 자체. 무엇을 통과해야 하는지는 바꾸지 않는다.
• 신규제작 여정에 매뉴얼 단계를 문서 화면에서 새로 세우는 일. 그 화면은 실제로 지나간 자취만 싣고, 이 저장소의 신규제작에는 아직 그 단계의 실물이 없다.
• 공개 문서 편수와 배치.

되돌릴 수 없는 것

외부 URL 허용 목록에 도메인을 하나 더 넣는 것은 공개 문서가 그 도메인으로 링크할 수 있게 되는 일이다. 목록은 두 곳에 있고 둘 다 고쳐야 하며, 한쪽만 고치면 빌드가 막힌다 — 그 이중화 자체가 안전장치이므로 한 곳으로 합치지 않는다.