구조도를 말로 그리기 — 업무 흐름·구조·상태 변화 그림 한 장 (archify)

도형을 하나씩 그리지 않고 말로 설명하고, 고칠 때도 말로 고칩니다. 클로드가 archify(아키파이)라는 도구(스킬)를 써서 그림을 그리고, 도구가 정한 검사를 통과해야 파일을 내줍니다. 그림은 다섯 종류입니다. 구성도(어떤 부품이 어떻게 붙어 있나), 업무 흐름도(일이 어떤 순서로 흐르나), 주고받는 순서(누가 누구에게 무엇을 보내나), 자료 흐름(자료가 어디서 어디로 가나), 상태 변화(어떤 상태에서 어떤 상태로 바뀌나)입니다. 이 편은 NCR(부적합 보고서) 처리 흐름을 그립니다. (예시 자료는 가짜 이름입니다.)

시작 전에

• 빈 폴더 하나를 만들고(이름은 영문으로, 예: 문서 폴더 안 draw), 그 폴더에서 클로드(Claude Code)를 엽니다. 데스크톱 앱이면 Code 탭에서 Local → Select folder, 터미널이면 그 폴더 안에서 claude 를 입력합니다. 설치·구독·승인 방식은 02편 「준비물 자세히」와 같습니다.
• 그림을 여는 것은 브라우저(크롬·엣지 등)입니다. 만들어진 HTML 파일을 더블클릭하면 됩니다. 받는 사람도 아무것도 설치하지 않고 열 수 있습니다.
• 클로드가 파일을 만들거나 명령을 실행하려고 허락을 물으면 무엇을 하는지 읽고 허락하세요. 이 편에서는 node 로 시작하는 명령과 그림 파일 쓰기가 나옵니다.
• 🤖 칸에 「예시 답」 이라고 적힌 것은 설치가 들어가는 단계라 실제로 돌리지 않고, 공식 안내로 답의 모양을 확인해 쓴 것입니다. 표시가 없는 답은 2026-10-10 에 실제로 돌려 받은 것을 줄였고, 줄인 곳은 「…」로 표시했습니다.

1단계 · archify 설치하기 (처음 한 번)

이미 깔려 있으면 건너뜁니다. 설치 명령을 클로드가 대신 실행하게 합니다. 설치 프로그램이 중간에 「어느 AI 도구에 깔까요?」 같은 질문을 하면 클로드는 거기에 답할 수 없으므로, 공식 옵션으로 미리 정해 줍니다. -a claude-code 는 「Claude Code 용으로」, -y 는 「설치 프로그램의 확인 질문은 건너뛰기」입니다. 대신 클로드의 허락 창이 뜨면 명령이 npx skills add tt-a1i/archify 로 시작하는지 내가 읽고 허락하세요.

✅ 이렇게 나오면 성공 — 클로드가 「archify 스킬이 설치됐다」고 하면 다음 단계로. 설치 뒤에는 클로드를 껐다가 같은 폴더에서 새로 여는 것이 안전합니다. (안 되면 「막히면」 5번.)

2단계 · 무엇을 그릴 수 있는지 묻기

그림을 그리기 전에, 클로드가 이 도구로 무엇을 그릴 수 있다고 하는지 확인합니다. 아무것도 만들어지지 않습니다.

✅ 이렇게 나오면 성공 — 위처럼 종류가 나열되면 다음 단계로. (「archify 를 모른다」고 하면 1단계 설치가 안 된 것입니다. 「막히면」 5번.)

3단계 · 흐름도 한 장 그리기

순서를 말로 설명합니다. 되돌아가는 길이 있으면 같이 말하세요. 클로드가 그림 종류를 고르고, 설명서를 쓰고, 검사하고, 파일을 만듭니다. 1~3분쯤 걸립니다.

✅ 이렇게 나오면 성공 — ncr-flow.html 과 ncr-flow.workflow.json 이 폴더에 생기고 「검사를 통과했다」는 말이 나오면 다음 단계로. (파일 이름은 달라도 괜찮습니다. 검사를 통과하지 못했다고 하면 「막히면」 4번.)

4단계 · 그림 열어 보기 (내가 직접)

이 단계는 클로드에게 말하지 않고 내가 직접 합니다.

1. 폴더에서 ncr-flow.html 을 더블클릭합니다. 브라우저에서 열립니다.
2. 왼쪽 위에 그림 제목이 있고, 상자가 다섯 개 가로로 이어집니다. 화살표가 「접수 → 원인 분석 → 시정조치 → 효과 확인 → 종결」로 이어지고, 효과 확인에서 시정조치로 돌아가는 점선에 「효과 미흡」 같은 글자가 적혀 있습니다. 상자 색과 점선 색, 그 글자는 클로드가 정하므로 매번 조금 다릅니다. 제 시험에서는 보라색 점선에 「효과 미흡」이 나온 적도 있고, 빨간 점선에 「효과 없음 → 재조치」가 나온 적도 있습니다.
3. 오른쪽 위에 Light(밝게/어둡게 바꾸기) · Classic(그림 스타일) · Present(발표 모드) · Export(내보내기) 단추가 있습니다. 영어로 보이는 것이 정상입니다.

✅ 이렇게 나오면 성공 — 상자 5개와 화살표, 되돌아가는 점선이 보이면 됩니다. 한글 글자가 그림 안에서 깨지지 않고 읽혀야 합니다. 빈 화면이면 「막히면」 6번.

5단계 · 말로 고치기

그림을 고치는 것도 말로 합니다. 클로드는 JSON 설명서를 고쳐서 다시 검사하고 같은 파일 이름으로 새 그림을 냅니다. 고친 뒤에는 4단계처럼 브라우저 탭을 새로고침해서 보세요.

✅ 이렇게 나오면 성공 — 새로고침한 그림에 「책임자 승인」 상자가 원인 분석 다음에 보이면 됩니다. 클로드가 「이렇게 정했는데 맞나요?」 하고 되물으면(위 답의 마지막 줄) 그대로 답해 주면 됩니다. 이렇게 내가 말하지 않은 것은 클로드가 정해서 알려 주는 것이 정상입니다.

6단계 · 다른 종류로 — 상태 변화

같은 NCR 을 이번에는 「상태가 어떻게 바뀌나」로 그립니다. 흐름도와 달리 되돌아가는 길(조치 중으로, 접수로)이 여러 개일 때 보기 좋습니다.

✅ 이렇게 나오면 성공 — 상태 변화 그림 파일(위 답의 ncr-state.html 처럼, 이름은 달라도 됩니다)이 생기고 「검사를 통과했다」는 말이 나오면 됩니다. 상태도 전용 형식이 검사에 걸리면 클로드가 위 답처럼 흐름도 형식으로 다시 그리기도 합니다(제 시험의 한 번에서 그랬습니다). 클로드가 정해서 그린 부분을 알려 주면, 내 업무에 맞게 「분석 중에서 반려되게 바꿔 줘」처럼 고치세요. 그림이 맞는지는 클로드가 아니라 업무를 아는 내가 판단합니다.

7단계 · 이미지로 저장해서 붙이기 (내가 직접)

문서·메일·발표에 넣으려면 이미지가 편합니다. 이 단계도 클로드에게 말하지 않고 내가 직접 합니다.

1. 브라우저에서 연 그림의 오른쪽 위 Export 를 누릅니다.
2. 목록에서 원하는 형식을 고릅니다. archify 안내에는 PNG·JPEG·WebP·SVG·WebM 으로 내보낼 수 있다고 적혀 있습니다(WebM 은 움직이는 그림).
3. 저장된 이미지를 문서나 메일에 붙입니다. 받는 사람이 그림을 직접 만지게 하려면 HTML 파일 자체를 보내세요(받는 쪽도 아무것도 설치하지 않고 브라우저로 엽니다).

✅ 이렇게 나오면 성공 — 이미지 파일이 저장되어 문서에 붙으면 끝입니다. 단추의 정확한 이름은 도구 버전에 따라 조금 다를 수 있습니다.

다 됐습니다 — 이제 이렇게 말하면 됩니다

항상 그림을 둘 폴더에서 클로드를 열고 이야기합니다. 「archify 로」를 앞에 붙이면 안전합니다.

• 「archify 로 우리 팀 월간 보고 순서를 흐름도로 그려 줘. 작성 → 팀장 검토 → 부서장 승인 → 제출이고, 검토에서 반려되면 작성으로 돌아가.」
• 「archify 로 메신저에서 AI 가 답하는 순서를 주고받는 순서 그림으로 그려 줘. 사람 → 메신저 → 서버 → AI 순서야.」
• 「archify 로 우리 사내 시스템 구성도를 그려 줘. 부품은 로그인, 업무 화면, 데이터베이스, 파일 서버야.」
• 「아까 그린 ncr-flow 에서 효과 확인 문구를 「재발 방지 확인」으로 바꿔 줘.」
• 「이 Mermaid 코드를 archify 로 보기 좋게 다시 그려 줘. (코드 붙여 넣기)」

막히면

1. 그림이 빽빽하거나 글자가 겹친다 → 상자가 너무 많은 경우가 흔합니다. archify 안내는 중심 상자 12개 이내로 시작하라고 합니다. 이렇게 말하세요: "상자를 12개 이내로 줄여서 다시 그려 줘. 합쳐도 되는 단계는 합치고, 중요하지 않은 화살표는 빼 줘."
2. 화면의 단추가 전부 영어다 → 그림 속 글자는 한글이지만, 보기 도구의 단추(Light·Present·Export 등)는 영어와 중국어만 지원한다고 클로드가 알려 줬습니다. 고칠 수 없는 부분이니 그냥 쓰세요.
3. 그림 아래쪽이 휑하다 → 상자가 적으면 그렇습니다. 클로드도 세로를 늘려 봤더니 빈 칸만 생겨 원래대로 되돌렸다고 했습니다. 고장이 아닙니다.
4. 「검사를 통과하지 못했다」, 같은 오류를 두 번 고치고도 안 된다고 한다 → 클로드가 남은 문제를 그대로 알려 주는 것이 정상입니다. 이렇게 말하세요: "남은 오류를 그대로 보여 줘. 상자나 화살표를 줄여서 다시 해 줘." 상태 변화 그림은 구역을 도구가 항상 3개 그리므로, 되돌아가는 길이 여러 개면 한 번에 안 풀릴 수 있습니다(제 6단계 시험에서는 한 번 고쳐서 통과했습니다).
5. 「archify 가 뭐야?」 하거나 그림 도구를 못 찾는다 → 설치가 안 됐거나, 설치 뒤 클로드를 다시 열지 않은 경우입니다(제가 직접 재현하지는 않았습니다). 클로드를 껐다가 같은 폴더에서 새로 열고 이렇게 말하세요: "archify 스킬이 보이는지 확인해 줘." 그래도 없으면 1단계를 다시 하세요.
6. HTML 을 열었는데 빈 화면이다 → 파일을 더블클릭해서 브라우저로 열었는지 보세요. 메모장 같은 글 편집기로 열면 코드만 보입니다. 브라우저에서도 빈 화면이면 이렇게 말하세요: "ncr-flow.html 을 다시 검사하고, 문제가 있으면 알려 줘."

한 번에 맡기기 (익숙해진 다음에)

역할: 너는 내 PC 에서 일하는 도우미다. archify 스킬로, 내가 말한 업무 흐름·구조·주고받는 순서·상태 변화를 보기 좋은 그림 한 장(HTML 파일 하나)으로 그린다. 나는 초보자이니 어려운 말은 풀어서, 한 단계씩 말해 줘.

맥락: archify 는 클로드 스킬이다. 입력은 작은 JSON 설명서이고, 출력은 브라우저로 여는 HTML 한 장이다. 그림 종류는 아키텍처(구성도)·워크플로우(업무 흐름도)·시퀀스(주고받는 순서)·데이터 흐름·생명주기(상태 변화) 다섯이다. 그림은 상자 12개 이내, 가운데 한 줄 흐름을 기본으로 한다. 스킬이 시키는 검증 순서(validate → deliver → visual-check)를 그대로 거친다. 아무것도 새로 설치하지 않는다.

입력: <운영체제>, <그릴 것: 예 NCR 처리 흐름>, <그림 종류: 모르면 비워 둠>, <단계나 부품 이름들: 예 접수 → 원인 분석 → 시정조치 → 효과 확인 → 종결>, <되돌아가거나 갈라지는 곳: 예 효과 확인에서 안 되면 시정조치로>, <파일 이름: 예 ncr-flow>

작업:
① 확인 — 아무것도 만들기 전에 먼저 본다.
 - archify 스킬을 쓸 수 있는지 본다. 쓸 수 없으면 아무것도 만들지 말고 멈춰서, 내가 npx skills add tt-a1i/archify -g -a claude-code -y 로 설치해야 한다고 안내한다(내가 허락하기 전에는 설치하지 않는다).
 - 지금 폴더에 <파일 이름>.html 이나 <파일 이름>.json 이 이미 있으면 덮어쓰지 말고 멈춰서 어떻게 할지 묻는다.
② 고르기 — 내 입력에 맞는 그림 종류를 고르고 이유를 한 줄로 말한다.
③ 그리기 — 스킬의 안내대로 JSON 설명서(<파일 이름>.json)를 쓰고, 검증하고, <파일 이름>.html 로 만든다. 그림 속 글자는 모두 한국어로 한다. 내가 말하지 않은 것(예: 상자 이름의 보조 설명, 되돌아가는 곳)은 네가 정한 것이니 따로 표시해서 알려 준다.
④ 점검 — 아래 「검증」을 파일을 다시 열어서 확인한다.
⑤ 마무리 — 초보자 눈높이로 파일을 여는 법(더블클릭하면 브라우저에서 열린다), 화면 위쪽 단추가 영어로 나오는 것, 그림을 고치고 싶을 때 하는 말(예: "원인 분석 다음에 승인 단계를 넣어 줘"), 그림을 이미지로 저장하는 법(화면의 Export 단추)을 설명한다.

제약: 비밀키·토큰·비밀번호·개인정보를 쓰지 않기. 오류나 검증 실패를 숨기지 않기(두 번 고쳐도 나아지지 않으면 멈추고 남은 문제를 그대로 알려 준다). 기존 파일을 지우거나 덮어쓰지 않기. 이 폴더 밖에 파일을 쓰지 않기. 내가 허락하기 전에는 아무것도 설치하지 않기.

출력: 한 일, 고른 그림 종류와 이유, 만든 파일 목록, 검증 결과((가)~(라) 각각 통과/실패), 내가 말하지 않아 네가 정한 것, 남은 문제와 다음 조치.

검증: 아래를 파일을 다시 열어서 전부 확인해야 "자동 확인 통과"라고 보고한다. 하나라도 실패하면 완료로 보고하지 말 것.
 (가) 이 폴더에 <파일 이름>.html 이 있다.
 (나) 이 폴더에 <파일 이름>.json(JSON 설명서)이 있다.
 (다) 스킬의 검증 명령이 오류 0·경고 0 으로 통과한다.
 (라) 그림 속 상자 이름이 내가 준 단계 이름과 같다.

내가 만들 때는

처음엔 이렇게 시켰습니다. 2026-09-16 09:12, 논문 같은 구조 그림 한 장을 보여 주며 파이스(제 개인 비서 AI)의 구조도 그렇게 그려 달라던 중에, 그런 그림을 보통 「아키텍처 다이어그램」이라 부른다는 말을 듣고 이렇게 말했습니다. 「아키텍처 다이어그램이라고 보통 하겠네.. 자 이걸 도구 실행하고 하는것 까직 전부 확장해서 모든 기능에 대해서 전부 그려줘」 이틀 뒤(9/18 09:26)에는 깃허브에서 소스를 찾은 archify 를 처음 불러 이렇게 시켰습니다. 「Archify로 시스템을 어떻게 짤껀지.. 아키텍처. 워크플로우. 시퀀스, 데이터 흐름, 생명중기.. 이거 각각 짜봐」 사내 메신저를 어떻게 만들지 다섯 종류 그림으로 먼저 그려 보라는 것이었고, 그날 설계 그림 다섯 장과 설계서가 나왔습니다. 9월 22일에는 다른 회사 자료를 읽은 뒤 「다시 청사진 그려줘.. 전체적인 구조를 다 그려줘.. archify로 그려줘」 라고 했고, 같은 도구로 전체 구조를 다시 그렸습니다.

실패도 있었습니다. 상태 변화(생명주기) 그림은 구역이 위·가운데·아래 셋뿐이고 이름을 따로 지은 구역이 전부 가운데 띠 하나를 같이 쓰는데, 이를 몰라 구역을 둘로 만들었다가 겹쳐서 헛돌았습니다. 흐름도는 구역(레인)이 넷이면 화면 아래로 넘쳤고, 화살표 하나에 글자 위치를 직접 지정하면 도구가 자동으로 나눠 주던 화살표 출발점이 합쳐져 두 화살표가 겹쳤습니다. 그림이 안 풀릴 때는 위치를 만지는 것보다 중요하지 않은 화살표를 없애거나 상자를 합치는 쪽이 훨씬 잘 들었습니다. 그래서 이 편에서도 「상자 12개 이내, 막히면 줄여 달라고 말하기」를 권합니다.

이렇게 익힌 뒤로 이 뒷이야기의 그림은 전부 같은 방법으로 그렸습니다. 단계마다 그림 1~2장의 설계(노드와 연결마다 근거를 단 글)를 먼저 쓰고, 클로드가 그것을 archify 로 그렸습니다. 그림 폴더에는 구성도·자료 흐름·상태 변화·주고받는 순서·업무 흐름 다섯 종류가 다 있습니다. 16단계(강좌 한 편이 나오기까지, 업무 흐름도)와 17단계(고장 하나가 규칙이 되는 길, 상태 변화)의 그림도 이렇게 나왔습니다.

→ 뒷이야기 16단계와 17단계에서 자세히 보세요.