03. 프로그램 모듈화 안내 — 어느 프로그램에서든

작성 2026-10-04 · 따르는 표준: 01_모듈_표준.md (표준 1) · 모듈 사이트: 02 이 폴더(docs/module-platform/)를 작업할 프로그램 저장소에 통째로 복사한 뒤 이 문서를 따르세요. 맨 끝 §9에 Claude에게 붙여 넣을 요청문이 작업별로 있습니다.

쉬운 요약 — 하려는 일에 따라 고르세요

절대 규칙: 이 프로그램 안에 들어온 모듈 사본(node_modules, site-packages, 복사된 폴더)은 고치지 않습니다. 고칠 일이 생기면 작업 D를 따릅니다. 이 프로그램이 고치는 것은 호스트 연결 파일(*.host.ts, *_host.py)뿐입니다.

1. 준비

1. docs/module-platform/을 이 저장소에 복사합니다.
2. 이 프로그램의 제품 코드를 확인합니다(라이센스 서버 products.product_code). 예: nahonza-work, zerolabel-saas.
3. 최상위에 modules.lock.json을 만듭니다. modctl이 있으면 modctl add 때 자동으로 만들어집니다.

``json { "lockVersion": 1, "product": "<제품 코드>", "modules": {}, "patches": [] } ``

1. 이 프로그램의 형태를 적어 둡니다. 작업 방법이 달라집니다.

위 표는 2026-10-04에 각 저장소의 package.json·requirements.txt를 열어 확인한 값입니다. PadCAD는 이번에 열어 보지 않았습니다.

1. 기본 모듈 확인(01 §2.5): 이 프로그램을 단독 설치로 팔 예정이면 license-guard·installer·update-agent 세 개가 반드시 들어가야 합니다. SaaS로만 운영하면 license-guard만 권장입니다. 이 프로그램 안에 자체 라이센스 확인 코드가 따로 있으면 기본 모듈로 바꾸는 것이 첫 작업입니다(작업 C).
2. 모듈 사이트·원본 저장소가 아직 없으면, 모듈 폴더를 이 저장소의 modules-out/<id>/에 01 §5 모양으로 만들어 둡니다. 원본 저장소가 생기면 그대로 옮깁니다.

2. 무엇을 모듈로 뺄까

2.1 판단표

2.2 지금 보이는 후보 (2026-10-04 기준, 제안)

3. 작업 A — 이 프로그램의 기능을 모듈로 빼내기

A1. 경계 조사 — 연결부 후보 찾기

• 도구로 한 번에: modctl extract <기능 폴더> --product <제품 코드> --dry 가 아래 조사(파일·바깥 import·환경변수와 보안 표시·주소·DB 표·연결부 제안)를 자동으로 합니다. --dry 를 빼면 모듈 센터 「모듈 후보」에 올라가, 다른 프로그램의 비슷한 후보와 합치고(§2.1 「이미 두 프로그램에 비슷한 코드」), 형태를 고르고(판단표), 뼈대(zip, EXTRACT.md 조사표 포함)를 받을 수 있습니다. 도구: 모듈 센터 /clients/modctl.js + /clients/extract.js.
• 그 기능의 파일 목록을 정합니다.
• 그 파일들이 기능 밖에서 import하는 것을 모두 적습니다. DB 클라이언트, 사용자 모델, 설정, 저장소, 알림, 기록, 환경변수가 대표적입니다.
• Node: grep -nE "^import|require\(" <파일들> 결과에서 기능 폴더 밖 경로만 추립니다.
• Python: grep -nE "^(from|import) " <파일들> 결과에서 app. 등 호스트 경로만 추립니다.
• 그 기능이 읽는 환경변수를 모두 적고, 각각 「보안 판단인가?」를 표시합니다(01 §10-1).
• 그 기능이 만드는 DB 표·주소(라우트)·화면을 적습니다.
• 👉 이 결과를 사람(대표님)에게 보여 주고 연결부 설계를 확인받은 뒤 A2로 갑니다.

A2. 연결부 정하기

• 바깥 의존 하나하나를 표준 연결부 이름(01 §6 표)에 맞춥니다. 맞는 게 없을 때만 새 이름을 만듭니다.
• 연결부 메서드마다 「없을 때는 무엇을 돌려주고, 실패하면 무엇을 던지는지」를 적습니다.
• 보안 판단 값(공개키·강제 여부·제품 코드)은 설정 칸이 아니라 코드 상수나 서명된 자료로 둡니다.

A3. 모듈 폴더 만들기와 코드 옮기기

• modctl init <id> --kind <종류> --runtime <언어>를 실행합니다. 도구가 없으면 01 §5 모양으로 손으로 만듭니다.
• 코드를 옮기면서 호스트 import를 연결부 호출로 바꿉니다.
• 진입점 하나(configure({ config, adapters }))를 만듭니다. 모듈 안에 전역 상태를 두지 않습니다.
• 이 프로그램 이름·도메인·회사명이 코드에 박혀 있으면 설정 칸으로 뺍니다. 단, 보안 판단 값은 예외입니다.

A4. 형식 맞추기 (스택별 주의)

• Node 모듈은 ESM과 CommonJS 둘 다 지원합니다(format: "esm+cjs"). 나혼자워크는 ESM, 제로라벨·라이센스 서버는 CommonJS입니다.
• TypeScript로 쓰고 tsc로 ESM 빌드와 CJS 빌드를 각각 내거나, 빌드 도구로 두 형식을 냅니다.
• package.json의 exports에 import/require를 모두 적습니다.
• Python: pyproject.toml 패키지로 만들고, 연결부는 typing.Protocol로 적습니다.
• 화면이 있는 모듈
• React: react·react-dom은 peerDependencies로 둡니다. 사용처의 Tailwind 클래스에 기대지 말고 접두사 CSS나 CSS 변수를 씁니다.
• EJS 같은 서버 렌더 화면(제로라벨): React 컴포넌트를 직접 쓰지 말고 스크립트 위젯이나 iframe으로 붙입니다.

A5. 검사 옮기기

• 그 기능의 기존 검사를 모듈의 test/로 옮기고, 가짜 연결부로 돌게 고칩니다.
• 두 판(Node·Python)이 있으면 contract/cases.json에 같은 입력·기대값을 넣습니다(01 §11.2).
• 회사 격리 모듈이면 「다른 회사 자료가 안 보인다」 검사를 반드시 넣습니다.

A6. 원래 프로그램을 모듈 사용으로 바꾸기

• 원래 코드를 지우고, 모듈을 설치(또는 modules-out/에서 로컬 연결)한 뒤 호스트 연결 파일을 만듭니다.
• Node: <서버>/src/modules/<id>.host.ts
• Python: app/modules/<id>_host.py
• 이 프로그램의 원래 검사가 그대로 통과해야 합니다. 이것이 「동작이 같다」는 증거입니다. 검사가 줄었거나 건너뛰었으면 실패로 봅니다.
• 낡은 빌드나 이미지로 검사하지 않았는지 확인합니다. 새로 빌드하고, 지금 도는 코드의 모듈 번호를 출력해 대조합니다.

A7. 문서와 첫 발행

• module.json, INTEGRATION.md(01 §12 목차), CHANGELOG.md(## 1.0.0)를 씁니다.
• modctl lint → modctl test → 원본 저장소에 올리고 태그 <id>-v1.0.0 → 모듈 사이트 등록·발행.
• modules.lock.json에 기록합니다.

A가 끝났다는 기준

• [ ] 모듈 안에 이 프로그램 경로 import 없음 (modctl lint 통과)
• [ ] 보안 판단 값이 환경변수로 바뀌지 않음
• [ ] 모듈 단위·약속 검사 통과
• [ ] 이 프로그램의 원래 검사가 줄지 않고 전부 통과
• [ ] 안내서에 「연결부 채우기」 예제가 있고, 그 예제대로 하면 실제로 돎
• [ ] modules.lock.json에 기록됨

4. 작업 B — 새 기능을 처음부터 모듈로 만들기

언제: 두 개 이상의 프로그램이 쓸 기능을 새로 만들 때입니다(예: 업데이트 도우미, 설치기).

1. 이름표부터 씁니다(module.json). 무엇을 연결받고(adapters), 무엇을 설정받고(config), 무엇을 내주는지(provides) 먼저 약속합니다.
2. 연결부 약속 파일(adapters.ts / adapters.py)을 씁니다.
3. 가짜 연결부로 개발·검사합니다. 특정 프로그램 없이도 돌아야 합니다.
4. 첫 사용처에 붙입니다(작업 C). 이때 연결부가 불편하면 발행 전에 고칩니다. 발행 후에 고치면 MAJOR입니다.
5. 두 번째 사용처까지 붙여 본 뒤 1.0.0을 발행하는 것을 권합니다. 그 전에는 0.x로 둡니다(0.x에서는 MINOR도 깨질 수 있다고 봅니다).

5. 작업 C — 모듈 가져오기

C1. 부품

modctl add license-guard            # 발행된 최신 번호
modctl add license-guard@1.4.0      # 지정 번호

도구가 하는 일

• Node: package.json에 "@hnbbos/license-guard": "1.4.0"(정확한 번호). .npmrc에 다음 두 줄이 필요합니다. `` @hnbbos:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN} ``
• Python: requirements.txt에 다음 줄을 넣습니다(비공개 저장소라 CI에서 읽기 토큰 필요). `` isolo-license-guard @ git+https://github.com/hnbbos/isolo_modules.git@license-guard-v1.4.0#subdirectory=modules/license-guard/python ``
• 호스트 연결 파일 뼈대를 만들고, modules.lock.json에 기록합니다.

그다음 사람이(또는 Claude가) 할 일

1. 모듈의 INTEGRATION.md를 읽고 호스트 연결 파일의 연결부를 채웁니다.
2. 안내서 「확인하는 법」의 항목을 이 프로그램 검사에 추가합니다.
3. 검사를 돌리고 modctl report를 실행합니다.

C2. 서비스

1. 소스를 가져오지 않습니다. 서비스 주소에 연결합니다.
2. 로그인 연결: 서비스 안내서대로 OAuth 앱을 등록하거나(나혼자워크 인가 서버는 앱 자동 등록 지원), 서비스가 주는 짧은 토큰을 받는 경로를 만듭니다.
3. 화면 끼워 넣기 — 셋 중 하나를 고릅니다.
4. iframe: <iframe src="https://<서비스 주소>/embed/…"> — 반드시 이 프로그램과 다른 주소(01 §10-9)
5. 스크립트 위젯: <script src="https://<서비스 주소>/widget.js"> + mount(…)
6. React 컴포넌트: @hnbbos/<id>-react (React 프로그램만)
7. 단독 설치 묶음에 포함: 서비스의 compose.fragment.yml을 이 프로그램의 단독 설치 구성에 넣습니다. 이미지는 지문(@sha256:)으로 고정합니다.
8. modules.lock.json에 kind: service, 번호, 이미지 지문을 기록합니다.

C3. 시작 틀 (새 프로그램을 만들 때)

modctl new saas-onprem-node ./my-new-app --var PRODUCT_CODE=my-app --var PRODUCT_NAME="새 프로그램" --var PORT=6601

• 만들어진 프로그램의 modules.lock.json에 saas-onprem-node의 번호와 appliedAt이 기록됩니다.
• 시작 틀에 들어 있던 부품(예: license-guard)은 복사가 아니라 패키지로 들어옵니다. 그래서 이후 작업 E로 새 번호를 받을 수 있습니다.

6. 작업 D — 고친 것을 모듈에 올리기 (다른 프로그램도 좋아지게)

D1. 평소 절차

1. 이 프로그램에서 문제를 재현합니다. 검사 하나로 만들면 가장 좋습니다.
2. 원본 저장소(isolo_modules)에 가지(branch)를 만들고 모듈 원본을 고칩니다.
3. 재현 검사를 모듈 검사에 추가합니다. 사용처 특유의 상황이면 가짜 연결부로 재현합니다.
4. 변경 크기를 정합니다(01 §7). 연결부·설정·표가 바뀌면 MAJOR입니다.
5. CHANGELOG.md에 새 번호 항목을 쓰고, 「사용처가 할 일」을 반드시 적습니다.
6. modctl lint → modctl test → PR → 리뷰 → 머지 → modctl bump → 태그 push.
7. CI가 모듈 사이트에 「검사 중」으로 등록합니다. 각 사용처의 검사 결과가 모입니다(3단계 전까지는 각 프로그램에서 수동으로 modctl check-report).
8. 모든 사용처가 통과하면 관리자가 발행합니다.
9. 이 프로그램은 작업 E로 새 번호를 받습니다.

D2. 이 프로그램에만 필요한 변경이라면

• 모듈을 고치지 말고 호스트 연결 파일에서 해결합니다.
• 연결부로 해결이 안 되면, 모듈에 선택 칸(설정)이나 선택 연결부를 추가하는 MINOR 변경으로 만듭니다. 다른 사용처의 동작은 그대로 둡니다.
• 「이 프로그램이면 이렇게」 같은 분기를 모듈 안에 넣지 않습니다.

D3. 긴급(보안·장애)일 때 — 임시 덧댐

1. 원본 저장소에 이슈를 먼저 엽니다.
2. 이 프로그램에서만 임시로 고칩니다. Node는 patch-package, Python은 연결부 쪽 우회를 씁니다.
3. modules.lock.json의 patches에 이유·이슈 주소·제거 기한을 적습니다. 적지 않은 덧댐은 금지입니다.
4. 같은 날 D1을 시작해 PATCH 번호를 냅니다. 받으면 덧댐을 지우고 patches에서도 뺍니다.
5. 기한이 지나면 modctl outdated와 모듈 사이트가 경고합니다.

7. 작업 E — 새 버전 받기

modctl outdated                       # 무엇이 뒤처졌나 (patch / minor / major, 회수 경고)
modctl update license-guard           # 같은 MAJOR 안의 최신으로
modctl update license-guard --to 2.0.0 --yes-major

1. update가 출력하는 「사용처가 할 일」을 먼저 처리합니다(새 설정 칸, 연결부 변경 등).
2. 이 프로그램 검사를 전부 돌립니다. 결과 줄이 없으면 실패로 봅니다.
3. 커밋합니다. 메시지에 모듈과 번호를 적습니다. 예: chore(modules): license-guard 1.4.0 → 1.5.0
4. modctl report를 실행합니다(CI가 하면 생략).
5. 회수된 번호를 쓰고 있다고 나오면 최우선으로 처리합니다. 다음 고침 번호로 올리거나 직전 번호로 내립니다.

고객 서버(단독 설치)에는 모듈을 하나씩 보내지 않습니다. 이 프로그램의 새 버전을 만들 때 모듈 사이트에서 묶음(프로그램 이미지 지문 + 모듈 번호)을 만들어 서명하고, 업데이트 도우미가 그 묶음을 받아 갑니다(02 §8).

8. 프로그램별 출발점 (2026-10-04 기준 제안)

나혼자워크

1. 라이센스 보호 장치를 처음부터 모듈로 붙입니다(작업 B, 제로라벨·라이센스 서버판을 합쳐 구멍을 막은 1.0).
2. 이미 고친 것: 다른 제품 키 거절(PRODUCT_CODE = 'nahonza-work' 코드 고정), 플랫폼 라이센스는 운영 콘솔만 관리. 이 두 가지는 모듈에서도 유지합니다.
3. 설치 형태 전환(EDITION=saas|onprem) 작업을 끝낸 뒤 그것을 시작 틀의 원본으로 정리합니다.
4. 저장소 추상층, OAuth·MCP는 두 번째 사용처가 생길 때 작업 A로 뺍니다.

제로라벨

1. lib/license-guard.js를 모듈 license-guard로 교체합니다(작업 C). CommonJS로 가져옵니다.
2. 환경변수로 공개키·강제 여부를 받던 부분은 모듈에서 없어지므로, 운영 환경변수 정리가 필요한지 확인합니다.
3. 화면이 EJS이므로 메신저 등 화면 모듈은 스크립트 위젯이나 iframe으로 붙입니다.

바코드 WMS

1. messenger_module/은 이미 연결부 3개(UserProvider/FileStorage/Notifier) + 끼워 넣기 위젯 + MANIFEST.txt(sha256)를 갖췄습니다. 이것을 표준 모듈로 바꾸는 작업은 다음과 같습니다.
2. module.json 추가: 번호는 위젯 번호 1.1.0을 이어받는 것을 권합니다.
3. 원본 위치를 정합니다(이 저장소 그대로 둘지, isolo_modules로 옮길지).
4. export_messenger_module.sh의 복사 방식을 「발행」으로 바꿉니다.
5. 표준 메신저를 이것으로 정하면 서비스 모듈(own-db, PostgreSQL)로 등록합니다.

라이센스 서버

1. lib/vendor/license-guard.js도 모듈 license-guard로 교체합니다. 서명하는 쪽이라 정규화(canonical)가 바이트 단위로 같아야 하므로, 약속 검사를 먼저 통과시킵니다.
2. 모듈 사이트(02)를 이 저장소에 만듭니다.

9. Claude 요청문 (복사해서 붙여 넣기)

모든 요청문 앞에: 「docs/module-platform/ 의 README, 01, 03 을 먼저 끝까지 읽어.」

A. 기능 빼내기

이 프로그램의 「<기능 이름>」을 모듈로 빼 줘.
docs/module-platform/01_모듈_표준.md 와 03_프로그램_모듈화.md 「작업 A」를 그대로 따라.

[순서]
1. A1 경계 조사 결과를 먼저 보여 줘: 기능 파일 목록 / 바깥 import 목록 / 읽는 환경변수(보안 판단 여부 표시) /
   만드는 DB 표·주소·화면 / 내가 제안하는 연결부(01 §6 표준 이름 우선).
   → 내가 확인하기 전에는 코드를 옮기지 마.
2. 확인 후 A2~A7. 원본 저장소가 없으면 modules-out/<id>/ 에 만들어.

[지킬 것]
- 모듈 안에서 이 프로그램 경로를 import 하지 마. 필요한 건 연결부로 받아.
- 보안 판단(공개키·강제 여부·제품 코드·권한)은 환경변수로 바꿀 수 없게 해.
- 연결부는 「없음(null)」과 「못 물어봄(예외)」을 구분해.
- 원래 프로그램의 검사가 줄지 않고 전부 통과해야 한다. 새로 빌드해서 돌리고, 도는 코드의 모듈 번호를 출력해 대조해.
- 끝나면 보고: 연결부 목록, 옮긴 파일, 모듈 검사·원래 검사 결과(통과/실패 수), A 완료 기준 체크, 남은 일.

B. 새 기능을 모듈로

「<기능 설명>」을 처음부터 모듈로 만들어 줘(03 「작업 B」).
쓸 프로그램: <프로그램 목록>. 종류는 01 §2.4 판단 순서대로 정하고 이유를 말해 줘.
1. module.json 과 연결부 약속(adapters)을 먼저 보여 주고 내 확인을 받아.
2. 가짜 연결부로 개발·검사한 뒤 첫 사용처(<프로그램>)에 붙여.
3. 두 번째 사용처에 붙이기 전까지 번호는 0.x 로 둬.

C. 가져오기

이 프로그램에 모듈 「<id>」(번호 <버전 또는 최신>)를 붙여 줘(03 「작업 C」).
- 모듈의 INTEGRATION.md 를 끝까지 읽고, 호스트 연결 파일만 이 프로그램에 맞게 작성해. 모듈 사본은 고치지 마.
- 버전은 정확한 번호로 고정하고 modules.lock.json 에 기록해.
- 안내서 「확인하는 법」 항목을 이 프로그램 검사에 추가하고 전부 돌려 결과를 보고해.
- 서비스 모듈이면 iframe 주소가 이 프로그램과 다른 원본인지 확인하고, 단독 설치 구성에 compose 조각을 지문(@sha256)으로 넣어.

D. 고친 것 올리기

모듈 「<id>」에서 이 문제를 찾았어: <증상>. 03 「작업 D」대로 처리해 줘.
1. 이 프로그램에서 재현하는 검사를 먼저 만들어.
2. 이 프로그램에만 필요한 변경인지(D2) 모두에게 필요한 고침인지(D1) 판단하고 이유를 말해 줘.
3. D1 이면 원본 저장소(isolo_modules, 없으면 modules-out/)에서 고치고, 변경 크기(patch/minor/major)와
   CHANGELOG 「사용처가 할 일」까지 써. 이 프로그램의 모듈 사본은 고치지 마.
4. 긴급이라 임시 덧댐이 필요하면 D3 대로 modules.lock.json patches 에 이유·이슈·기한을 적어.

E. 새 버전 받기

modctl outdated 결과를 보여 주고, <id> 를 <번호> 로 올려 줘(03 「작업 E」).
- 그사이 CHANGELOG 「사용처가 할 일」을 먼저 모아서 보여 주고 처리해.
- MAJOR 면 바꿔야 할 곳 목록을 먼저 보여 주고 내 확인을 받아.
- 검사를 전부 돌려 결과를 보고하고, 커밋 메시지에 모듈과 번호를 적어.

10. 자주 막히는 곳