1. SONNUN을 이용하기 전에
SONNUN은 "AI가 진행한 작업을 믿을 수 있는가?"라는 질문에 답하기 위한 AI 협업 통제 시스템입니다.
네 개의 축
- 자산 지식화 — 내 컴퓨터의 정보 자산(문서·코드)을 AI가 이해할 수 있는 정본 지식으로 변환합니다.
- AI 협업 — AI가 언제·무엇을·어떻게·왜 바꿨는지 추적 가능한 형태로 함께 일합니다.
- 위험 판정 — 작업의 위험 수준을 정량 평가하고 안전한 가이드를 제공합니다.
- 검증 결과 — AI의 말이 아니라 실제 증거에 기반해 사람이 승인 여부를 판단합니다(Human-in-the-Loop).
왜 통제가 필요한가 — 통제 없는 AI는 요청하지 않은 파일을 건드리고, 검증 없이 "완료"라 보고하고, 구조를 모른 채 넓게 추측 수정하며, 작업량이 늘수록 사람이 다 검토할 수 없게 됩니다.
작업 전 못 박는 6가지 — ①수정 경계(허용된 작업 공간·파일인가) ②정본 근거(추측이 아닌 색인된 구조 기반인가) ③위험 수준 ④검증 계획 ⑤보고 양식 ⑥사람 승인. AI는 이 틀 안에서만 움직입니다.
SONNUN은 내 PC에 설치하는 프로그램입니다 — 내 문서가 PC 밖으로 나가지 않는 것이 SONNUN의 존재 이유라, 아무것도 설치하지 않고 웹 브라우저만으로는 쓸 수 없습니다. SONNUN 자체는 무료로 사용할 수 있고, AI와의 연결 가능 범위는 각 AI 서비스(OpenAI·Anthropic·Google)의 요금제·정책을 따릅니다(SONNUN이 제한하는 것이 아닙니다).
앱으로 쓰기 — 설치하면 자동 연결, 별도 설정 없음
| 사용하는 AI | 지원 |
|---|---|
| ChatGPT 데스크톱 앱(Codex 화면) | 무료 포함 전 요금제 |
| Claude 데스크톱 앱 | 무료 포함 |
| Claude Code | 유료 전용 |
웹(브라우저)으로 쓰기 — 연결 주소 등록 1회 필요
| 서비스 | 지원 |
|---|---|
| claude.ai 웹 | Pro 요금제부터(권장) |
| chatgpt.com 웹 | 기업용(Business/Enterprise/Edu) — 개인 무료·Plus 불가 |
| Gemini 웹 | 현재 한국 미지원 |
개인 사용자는 데스크톱 앱 사용을 권장합니다(무료로 전 기능). 웹은 위 요금제 조건이 맞을 때만 연결되며, 이는 각 AI 서비스의 정책이지 SONNUN의 제한이 아닙니다.
SONNUN is an AI-collaboration governance system built to answer one question: "Can you trust what the AI just did?"
Four pillars — Asset Knowledge (turns your local documents/code into canonical knowledge), AI Collaboration (every change is traceable — when, what, how, why), Risk Verdict (quantifies task risk), Verified Outcome (humans approve on real evidence, not the AI's word).
Why govern — Ungoverned AI touches files you never asked for, declares "done" without verifying, edits broadly by guesswork, and outpaces human review.
Six things nailed down before work — edit boundary, canonical grounding, risk level, verification plan, report format, human approval. The AI moves only inside this frame.
1-1. 어디서 쓸 수 있나 · Supported Environments
SONNUN is a program installed on your PC — keeping your documents from leaving your machine is its whole purpose, so it cannot be used from a web browser alone with nothing installed. SONNUN itself is free; what you can connect to depends on each AI provider's plan and policy (OpenAI / Anthropic / Google), not a SONNUN restriction.
Via app (auto-connect, no setup) — ChatGPT desktop (Codex): all plans incl. free · Claude desktop: incl. free · Claude Code: paid only.
Via web (one-time connector registration) — claude.ai: Pro and up (recommended) · chatgpt.com: Business/Enterprise/Edu only (not free/Plus) · Gemini web: not available in Korea yet.
Individuals should prefer the desktop app (full features, free). Web connects only when the plan conditions above are met — a policy of each AI provider, not a SONNUN limit.
2. SONNUN을 이용한 작업 진행
문서작업이든 코딩작업이든, 권장 순서는 같습니다.
1) 먼저 AI에게 이렇게 말하세요: "MCP tool을 확인하라."
AI가 SONNUN 도구 목록(작업 등록 도구 cgos_route, 문서작업 도구 document_*, 지식검색 도구 등)을 인지하게 됩니다. 이 한 마디로 AI는 파일을 통째로 읽는 대신 SONNUN의 색인·집계를 활용하게 되어 작업이 빨라지고 토큰(비용)이 크게 절약되며, 모든 변경이 통제 경로를 타게 됩니다.
2) 작업을 지시하세요. 대상 파일/폴더를 함께 말해주면 더 좋습니다(예: "a.py의 X 버그를 고쳐라"). SONNUN이 대상 파일의 구조 지도를 AI에게 미리 쥐여 주어 재읽기 낭비가 없습니다.
3) AI는 후보 작업공간에서만 작업합니다. 원본(정본)은 이 단계에서 절대 바뀌지 않습니다.
4) 품질 게이트가 자동 검사합니다. 파이썬은 800줄 한도·비대화(성장률) 제한·기존 설명주석(docstring) 보존·구문 검사, 그 외 언어(C/C++/JS/Java 등 50여 종)도 머리주석 보존·크기·구문을 검사합니다. 걸리면 AI가 다시 고쳐야 합니다.
5) 승격 티켓이 만들어지고, 최종 반영은 사용자의 승인으로만 이뤄집니다. (다음 절 참조)
For documents or code, the recommended flow is the same.
1) Start by telling the AI: "Check your MCP tools." The AI discovers SONNUN's tools (task registration cgos_route, document tools document_*, knowledge search). This one sentence makes the AI use SONNUN's index and server-side aggregation instead of reading whole files — faster work, far fewer tokens, and every change rides the governed path.
2) Give the task. Naming the target files helps (e.g., "fix bug X in a.py"); SONNUN hands the AI a structure map of the targets so nothing is re-read wastefully.
3) The AI works only in a candidate workspace. Originals never change at this stage.
4) Quality gates run automatically. Python: 800-line cap, growth-ratio cap, docstring preservation, syntax check; other languages (50+ incl. C/C++/JS/Java): header-comment preservation, size, syntax. Failures bounce back to the AI.
5) A promotion ticket is created — nothing lands without your approval. (Next section.)
3. 승격 절차
승격(promotion)이란 AI가 후보 작업공간에서 만든 변경을 정본(원본)에 반영하는 단계입니다. 승격 전까지 원본은 바이트 하나 바뀌지 않습니다.
승인하는 두 가지 방법
- 브라우저(10183) 메인 → "승인 티켓 처리" 카드: 대기 티켓에서 변경 요약과 대상 파일을 확인 → [OTP 코드 요청] 클릭 → 화면에 표시된 6자리 코드를 60초 안에 입력 → [승인]. 원치 않으면 [취소]로 폐기합니다.
- 시스템 트레이 팝업: 승격 요청이 생기면 팝업이 떠서 변경 파일 목록·요약·예상 토큰 절감(실측 기반)을 보여줍니다. 승인/거부를 바로 선택할 수 있습니다.
안전 장치
- 승인 없이 반영되는 경로는 없습니다(전 과정 원장 기록·서명).
- 승격 반영 내역은 메인 하단 "승격 이력"에서 누가·언제·무엇을 반영했는지 확인할 수 있습니다.
- 서버 코드가 반영된 경우 서버가 자동 재시작될 수 있습니다(문서·UI 파일은 새로고침만으로 반영).
Promotion is the step where the AI's candidate changes land on the canonical originals. Until then, not a single byte of your originals changes.
Two ways to approve
- Browser (10183) main → "Approval Tickets" card: review the summary and target files → [Request OTP Code] → enter the shown 6-digit code within 60 seconds → [Approve], or [Cancel] to discard.
- System-tray popup: shows changed files, a summary, and measured token savings; approve or reject on the spot.
Safeguards — there is no path that lands without approval (full ledger + signatures); the "Promotion History" panel shows who/when/what; server-code promotions may auto-restart the server (docs/UI need only a refresh).
4. LLM 지시어 및 작업 예
아래는 실제로 동작이 검증된 지시 패턴입니다. 공통 요령: 첫 마디는 "MCP tool을 확인하라", 그리고 대상(파일·폴더)을 구체적으로.
코딩
- "MCP tool을 확인하라. glg/ui/dev/settings-panel.js의 저장 버튼이 동작하지 않는다. 원인을 찾아 고치고 승격 티켓까지 만들라."
- "이 폴더의 파이썬 파일에서 X 함수를 쓰는 곳을 모두 찾아라." (색인 기반 — 파일 통독 없이 답)
문서작업 (값은 서버가 처리 — 개인정보는 AI에게 보이지 않음, §5)
- 명단 병합: "4월·5월 이용자명단을 병합하고 중복 인원을 제거해 새 파일로 만들어라."
- 인원 집계: "5월 명단에서 장애유형이 발달장애인 사람이 몇 명인지 세라." (숫자만 반환)
- 서식 보존 번역: "이 보고서(docx)를 영어로 번역하되 원본 서식·표·테마를 그대로 유지한 사본으로 저장하라."
- 초안 저장: "오늘 회의 내용을 회의록 형식으로 정리해 회의록_0709.docx로 저장하라."
지식 검색·회상
- "우리 관제 폴더에서 재활치료 지원 기준에 대한 문서를 찾아 요약하라."
- "어제 SONNUN으로 진행한 작업 목록을 회상하라."
주의 — "전부 삭제하라" 같은 파괴 지시는 SONNUN이 거부합니다. 폴더 관제 해제는 설정 화면의 [제거] 버튼으로 직접 하세요(실제 파일은 삭제되지 않음).
Proven prompt patterns. Rule of thumb: open with "Check your MCP tools", and name your targets.
Coding — "Check your MCP tools. The save button in glg/ui/dev/settings-panel.js doesn't work; find the cause, fix it, and raise a promotion ticket." / "Find every caller of function X in this folder." (index-backed, no full reads)
Documents (values are processed server-side — the AI never sees PII, §5) — merge rosters & dedupe into a new file; headcount by condition (returns numbers only); translate a docx into a format-preserving copy; save meeting notes as 회의록_0709.docx.
Search & recall — "Find and summarize documents about rehab-support criteria in our managed folders." / "Recall what we did with SONNUN yesterday."
Note — destructive orders ("delete everything") are refused. To stop managing a folder, use the [Remove] button in Settings (real files are untouched).
5. 문서 보호 (개인정보)
원칙: 개인정보 값은 AI 채널을 절대 통과하지 않는다.
AI에게 명단 작업을 맡겨도, 이름·주민등록번호·연락처 같은 실제 값은 AI에게 전달되지 않습니다.
실제 동작 방식:
- 집계는 서버가 수행 — "몇 명인지 세라", "병합하라" 같은 작업은 SONNUN 서버가 파일 안에서 직접 처리하고, AI에게는 결과 숫자·행수·확인용 지문(해시)만 돌아갑니다.
- 개인정보 항목은 번호표(handle)로 — AI가 특정 항목을 다뤄야 할 때는 실제 값 대신 번호표와 마스킹된 예시(예: 김○○)만 봅니다. 수정도 번호표를 지목하면 서버가 값을 보지 않는 AI 대신 직접 바꿉니다(블라인드 수정).
- 자격증명은 색인조차 안 됨 — 비밀번호 파일·API 키·인증서 등은 하드플로어 규칙이 색인 단계에서 원천 차단합니다.
- 관제 해제 = 색인 전량 삭제 — 설정에서 폴더를 [제거]하면 그 폴더의 색인·검색 데이터가 즉시 전부 삭제됩니다(디스크의 실제 파일은 그대로).
- AI가 원문을 우회해 읽으려 하면 거부 — 통제 경로 밖의 원문 통독 시도는 반출로 간주해 차단됩니다.
Principle: personal-data values never cross the AI channel. Even when you hand roster work to the AI, real names, ID numbers, and contacts are never delivered to it.
How it actually works — aggregation runs server-side (the AI receives only counts, row numbers, and verification hashes); PII items are exposed as numbered handles with masked samples, and edits are applied blind by the server; credential files are excluded from indexing at a hard floor; unmanaging a folder purges its entire index immediately (real files untouched); attempts to read raw content outside the governed path are refused as exfiltration.
6. 바이러스로부터 문서 보호
문서 파일(hwp·doc·xls 등)에는 실행 코드가 숨어 들어올 수 있습니다 — 매크로, 문서로 위장한 실행파일, 스크립트 조각 등. SONNUN의 문서 검사기(avguard)는 관제 폴더의 문서를 이렇게 지킵니다.
- 구조 기반 검사 — 단순 문자열 검색이 아니라 문서 형식의 실제 구조(저장 단위 경계)에 맞춰 검사해, 정상 문서를 바이러스로 오인하는 일을 최소화합니다.
- 탐지 시 조치 — 의심 문서는 알림을 띄우고 격리 보관합니다. 격리는 삭제가 아닙니다 — 원본은 지문(해시)으로 무결성을 확인한 뒤 언제든 복원할 수 있습니다.
- 자동 격리는 선택제 — 자동으로 옮길지, 알림만 받을지는 사용자가 정책으로 선택합니다.
정직한 한계 — avguard는 문서형 위협에 대한 1차 방어선이며, 백신(안티바이러스)을 대체하지 않습니다. 백신과 함께 쓰는 것을 권장합니다.
Document files (hwp, doc, xls…) can carry hidden executable content — macros, executables disguised as documents, script fragments. SONNUN's document guard (avguard) protects managed folders with structure-aligned scanning (checked against the file format's real storage boundaries, minimizing false alarms on healthy documents), alert + quarantine on detection (quarantine is not deletion — originals are hash-verified and restorable anytime), and opt-in auto-quarantine (you choose: auto-move or alert-only).
Honest limit — avguard is a first line of defense for document-borne threats; it complements, not replaces, your antivirus.
7. 부록: 화면 안내
- 메인(대시보드) — ①시스템 런타임 상태(DB 통계) ②SONNUN-LLM 절감(예상): 누적 절감 토큰·호출 횟수·예상 절약 금액(OPUS 4.8기준) ③SONNUN 스키마: 지식 구조(노드/엣지 타입·보존 정책·인제스트 권한·TTL) ④승인 티켓 처리 + 하단 승격 이력.
- ROMIS — 지식 그래프 시각화(Graphify). 노드 검색·코드 아키텍처 뷰·거버넌스 준수 뷰. [ROMIS 갱신]으로 재동기화.
- 설정 — 일반(서버 상태·재시작) / 관제 디렉토리(폴더 추가·제거, 총 사용량과 플랜) / Model Tool(AI 도구 연결·테스트) / 운영 설정 / 코딩설정(Doc String·줄 한도·다언어 게이트) / 결제(플랜 전환).
- 언어 — 우상단 EN/한국어 토글. 한 번 바꾸면 전 화면에 적용됩니다.
- Main (Dashboard) — System Runtime (DB stats) · SONNUN-LLM Savings (est.): cumulative tokens, calls, est. cost saved (OPUS 4.8 basis) · SONNUN Schema (node/edge types, retention, ingest permissions, TTL) · Approval Tickets + Promotion History below.
- ROMIS — knowledge-graph view (Graphify): node search, code-architecture and governance views; [ROMIS Refresh] to resync.
- Settings — General (server status/restart) / Managed Directories (add/remove folders, usage vs plan) / Model Tool (connect & test AI clients) / Operations / Coding (docstring, line cap, polyglot gate) / Billing (plan switch).
- Language — EN/한국어 toggle at top right; one switch applies everywhere.