초보 바이브코더를 위한 Claude Code / Codex 플러그인입니다. "AI에게 제대로 일 시키는 법(계획 먼저 → 실행 → 검토 → 안전)"을 쉬운 한국어로 떠먹여 주는 도구입니다. 이 문서 하나로 설치부터 문제 해결·라이선스까지 전부 확인할 수 있습니다. AI·컴퓨터·스마트폰을 처음 다루는 분도 그대로 따라 하실 수 있게 썼습니다.
🇺🇸 English version: README.en.md (동일한 내용, 동일한 순서)
⚠️ 현재 상태(정직하게): Phase 1(MVP, F1F5)·Phase 2(F6 안전 기록·F7 Codex 안전 패리티)는 코드 완료 상태입니다. Phase 3 진입 게이트 1·2·3(사람의 실제 확인이 필요한 항목들)은 2026-08-20 기준 전부 통과했습니다 — 게이트 1은 처음엔 F8을 사용자가 먼저 승인해 정식 종결 전에 착수한 상태였지만(우회 시작, 아래 기록은 그 시점 그대로 보존), 이후 F2/F3 배너 반복 실측이 실제로 완료되며 정식으로 닫혔습니다. F8(쉬운 모드)은 사용자가 지정한 범위까지 구현을 마쳤고, 이후 추가 확장은 의도적으로 멈춘 상태입니다(근거 없는 확장은 과설계라는 판단,v0.2.8): 실사용 테스트 중 안전장치(훅) 자체의 결함 4건을 새로 찾아 전부 고쳤습니다 — 그중 하나(노트북 파일 편집 시 키 노출 검사가 완전히 빠져 있던 문제)는 지금까지 발견된 것 중 가장 심각한 유형이었습니다. 전부 자동 테스트로 재현·수정·재검증을 마치고 저장소에 반영했습니다. 자세한 내용은 §8 업데이트 내용 요약 최신 항목을 참고하세요.v0.2.2시점). 지금은 사람의 실사용 피드백을 기다리는 단계입니다. 그 외 일부 항목은 여전히 "코드·자동 테스트는 통과, 사람이 실제 화면으로 확인하는 것만 남음" 상태입니다 — 과장하지 않고 §8 업데이트 내용 요약의 최신 항목에 정리해 뒀습니다. 🔧 2026-09-01 안전 점검 라운드(v0.2.5⚠️ GitHub 저장소는 공개(PUBLIC) 상태입니다. 다만 이 프로젝트는 여전히 개발자 본인이 실제로 쓰려고 만든 개인용 도구이며, 다수 사용자를 위한 정식 배포·지원을 제공하지는 않습니다. 아래 라이선스 조건(Apache-2.0)은 공개 상태를 실제로 반영한 것입니다.
- 프로젝트 소개
- 사전 준비물
- 필요 프로그램 / 다운로드 방법
- 빠른 시작 (5분 골든패스)
- 설치 방법
- 실행 방법 / 사용 방법 / 작동 방법
- 명령어 목록
- 업데이트 내용 요약
- 파일 / 문서 위치
- 워크플로우
- 아키텍처
- 보안 · 데이터 흐름
- 문제 · 오류 대처
- FAQ (자주 묻는 질문)
- 법률 · 저작권 · 라이선스 · 상업적 용도
- 제거 방법
- 기여 / 문의
- 권장 MCP (선택, 참고용)
소담 에이전틱은 "AI에게 일을 제대로 시키는 법"을 쉬운 한국어로 떠먹여 주는, Claude Code(또는 Codex)용 플러그인(=AI 프로그램에 기능을 더해주는 부품)입니다. 새 작업을 시키면 코드를 바로 짜지 않고 ①무엇을 ②왜 ③완성 기준을 먼저 한국어로 보여주고 승인을 받고(계획 먼저), 작업이 끝나면 무엇을·왜 바꿨고 위험은 없는지를 쉬운 말로 요약해 주며(변경점 검토), 위험한 명령이나 비밀정보 노출 시도는 자동으로 막거나 확인을 받습니다(안전 훅).
비유하자면 AI는 공장의 기계이고, 당신은 그 공장을 설계하는 사람입니다. 기계에 그냥 "알아서 해"라고 맡기는 게 아니라, 무엇을·왜·어디까지 만들지 먼저 정하고, 기계가 한 일을 사람이 검토하고, 위험한 동작은 자동으로 걸러냅니다.
대상: 코딩을 전혀 몰라도 AI에게 자연어로 시켜서 뭔가를 만들어보고 싶은 비개발자·바이브코더입니다. 전문 용어가 나오면 그때그때 괄호로 쉽게 풀어 설명합니다.
| 준비물 | 왜 필요한가 | 필수 / 선택 |
|---|---|---|
| Node.js 18 이상 | 안전장치(훅)가 이걸로 돌아갑니다. 없으면 안전 기능 자체가 안 켜집니다 | 필수 |
| Claude Code (또는 Codex) | 소담이 설치되는 프로그램입니다 | 필수 (둘 중 하나) |
| GitHub 계정 | 소담은 GitHub(인터넷 코드 창고)에서 받습니다. 저장소가 공개(PUBLIC) 상태라 별도 접근 권한 없이 누구나 설치할 수 있습니다 | 선택 |
| git (명령줄 도구) | Codex 설치 경로에서만 필요합니다 — Codex는 git clone으로 저장소를 통째로 내려받은 뒤 설치 스크립트를 실행하는 방식이기 때문입니다. Claude Code 마켓플레이스 설치는 git이 필요 없습니다 |
필수 (Codex 설치 시에만) |
| 인터넷 연결 | 설치할 때 필요합니다(설치 후 이 플러그인 자체는 네트워크 요청을 보내지 않습니다 — §12 참고) | 필수 (설치 시점만) |
💡 확인 방법: 터미널(검은 창)에
node -v입력 →v18.이상 숫자가 나오면 OK.
- 공식 사이트 https://nodejs.org 접속 → 초록색 "LTS" 버튼을 클릭해 내려받습니다.
- 받은 설치 파일을 더블클릭 → "다음 → 다음 → 설치"(기본값 그대로 두면 됩니다).
- 설치 후 컴퓨터를 한 번 껐다 켜면 확실합니다.
- 확인: 터미널에
node -v→ 버전 번호가 뜨면 완료.
- 이미 Claude Code를 쓰고 계신다면 건너뛰세요(지금 이 대화가 Claude Code일 수 있습니다).
- 처음이라면 공식 안내(https://code.claude.com)를 따라 설치하세요(Node.js가 먼저 깔려 있어야 합니다).
- Codex CLI 자체 설치는 OpenAI 공식 안내를 따르세요. 이 플러그인은 Codex를 설치한 이후에 스킬을 추가하는 방식입니다 → §5 설치(Codex).
- 설치 — Claude Code 입력칸에 그대로 붙여넣고 Enter:
/plugin marketplace add https://github.com/sodam-ai/SoDam-Agentic-Eng /plugin install sodam-agentic@sodam-agentic - 시작 —
/sodam-agentic:start입력 → 한국어 온보딩 안내가 뜹니다. - 시키기 — "○○ 만들어줘"라고 자연어로 부탁 → 계획이 먼저 뜨면 "네/진행"으로 승인 → 작업 완료 후 검토 요약 확인.
→ 여기까지 5분이면 "됐다"는 경험이 끝납니다. 확인·진단 명령부터 앞세울 필요 없이, 그냥 시키는 게 먼저입니다.
⚠️ 현재 저장소는 공개(PUBLIC) 상태입니다. 별도 접근 권한 없이 아래 명령이 그대로 성공합니다.
- 마켓플레이스("플러그인 가게") 등록 — 입력칸에 그대로 붙여넣고 Enter:
→ "추가됨" 계열 메시지가 보이면 성공.
/plugin marketplace add https://github.com/sodam-ai/SoDam-Agentic-Eng - 설치:
→ "installed / 설치됨"이 보이면 성공.
/plugin install sodam-agentic@sodam-agentic⚠️ 마켓플레이스 이름을 정확히 쓰세요. 반드시sodam-agentic@sodam-agentic형태로 입력하세요. 마켓플레이스 이름은.claude-plugin/marketplace.json의name값과 정확히 일치해야 합니다(@sodam처럼 줄이면 실패합니다). - 확인:
/sodam-agentic:까지만 입력 → 명령 5개(start,plan,review,log,f8-easy)가 자동완성으로 뜨면 완료.
(참고, 로컬 테스트용) 인터넷 주소 대신 내 컴퓨터의 폴더 경로로도 등록할 수 있습니다:
/plugin marketplace add D:/AI_Dev_Work/2026y/26y_06m_26d_SoDam-Agentic-Eng
/plugin install sodam-agentic@sodam-agentic
- 이 저장소를 클론합니다:
git clone https://github.com/sodam-ai/SoDam-Agentic-Eng - 내 프로젝트 폴더 안에서 설치 스크립트를 실행합니다(클론한 경로로 바꾸세요):
node C:\경로\SoDam-Agentic-Eng\codex\install.mjs⚠️ 폴더 실수 주의: 반드시 작업하려는 프로젝트 폴더로 먼저 이동(cd)한 뒤 위 명령을 실행하세요. 설치 스크립트는 "지금 명령을 실행한 폴더(현재 위치)"를 기준으로.agents/·.codex/를 만듭니다. 엉뚱한 폴더에서 실행하면 스킬·안전 훅이 그 폴더에 설치됩니다. - 완료: 스킬이 내 프로젝트의
.agents/skills/에 복사되고,AGENTS.md가 프로젝트 루트에 복사되며(이미 있으면 덮어쓰지 않음), 안전 훅(hooks/guard.mjs+hooks/delegate.mjs)과 규칙 데이터(data/agentic-rules.json)가.agents/hooks/·.agents/data/에 복사되고,.codex/hooks.json에PreToolUse항목으로 자동 등록됩니다(기존 파일이 있으면 병합, 중복 등록 방지).
⚠️ Codex에도 같은 안전 훅(F4)·안전 기록(F6)이 그대로 등록됩니다. 계획(F2)·검토(F3) 스킬도 동일하게 동작합니다. 다만 Codex 화면에서 확인(ask) 창이 실제로 뜨는지는 아직 사람이 직접 라이브로 확인하지 않았습니다 — 자세히: §12 보안·데이터 흐름, §8 업데이트 내용 요약의 최신 항목.
가장 단순한 사용법(먼저 해볼 것):
/sodam-agentic:start입력 → "AI에게 일 시키는 4단계" 온보딩을 한 번 읽습니다.- 자연어로 그냥 시킵니다. 예: "메모장 웹페이지 만들어줘". 확인·진단 명령부터 앞세울 필요 없습니다 — 그냥 시키는 게 먼저입니다.
- AI가 코드를 짜기 전에 "①무엇을 ②왜 ③완성기준" 계획을 보여주면, 읽고 "네" / "진행" 이라고 답해 승인합니다.
- 작업이 끝나면 "무엇을·왜 바꿨고 위험은?" 요약을 읽고 사람이 최종 판단합니다.
놓치기 쉬운 한 가지(권장):
/init을 한 번 실행해두면 AI가 지금 폴더(프로젝트)를 더 잘 인식합니다. 초보자가 가장 잘 건너뛰는 단계입니다.
그래도 이해가 안 되면(F8):
- "설명이 너무 어려워요" / "하나도 모르겠어요"라고 말하면 F1보다 더 쉬운 설명(F8, 쉬운 모드)이 자동으로 뜹니다. 바로 부르고 싶으면
/sodam-agentic:f8-easy. 설명만 더 쉬워질 뿐, 안전 절차(F2·F3·F4)는 이 모드와 무관하게 항상 똑같이 작동합니다 — 자세히: §14 FAQ.
내부에서 자동으로 일어나는 것(사람이 신경 쓸 필요 없음):
- AI가 파일을 쓰거나 명령을 실행하려는 매 순간마다, 소담의 안전 훅이 먼저 끼어들어 안전/확인/차단을 판정합니다(§11 아키텍처의 "판정 흐름" 참고). 이건 사람이 아무것도 안 해도 항상 자동으로 동작합니다.
| 명령 | 언제 쓰나 |
|---|---|
/sodam-agentic:start |
처음 시작할 때 — 온보딩(4단계 안내) + 안전 상태 점검 |
/sodam-agentic:plan |
"계획 먼저" 기능을 지금 당장 직접 다시 보고 싶을 때(보통은 새 작업 요청 시 자동 발동) |
/sodam-agentic:review |
"변경점 검토"를 지금 당장 직접 다시 보고 싶을 때(보통은 파일 변경 직후 자동 발동) |
/sodam-agentic:log |
지금까지 안전장치가 막았거나(deny) 확인받은(ask) 기록을 조회할 때(F6) |
/sodam-agentic:f8-easy |
"설명이 너무 어려워요"처럼 F1 온보딩보다 더 쉬운 설명이 필요할 때(F8, 자연어로 말해도 자동 발동) |
형식은
/플러그인이름:명령입니다. 새 대화창을 열고/sodam-agentic:까지만 입력해도 5개가 목록으로 뜹니다.
아래는
CHANGELOG.md의 실제 이력을 날짜별로 요약한 것입니다(최신순). 각 항목을 클릭하면 펼쳐집니다.
🔴 2026-09-01 — 실사용 테스트 중 안전장치 결함 4건 발견·수정 (v0.2.5~v0.2.8)
지금까지 구현된 기능이 실제로 잘 작동하는지 여러 각도로 반복 테스트하다가, 안전장치(훅) 자체의 결함 4건을 새로 찾아 전부 고쳤습니다. 전부 "완전히 안 막던 것"이 아니라 "특정 상황에서만 놓치던" 결함이며, 발견 즉시 재현 → 원인 분석 → 수정 → 자동 테스트 재검증 순서로 처리했습니다.
- v0.2.5 — 치명 명령 판정 순서 결함:
rm -rf ~처럼 되돌릴 수 없는 명령이, 그 대상이 "작업폴더 밖"에도 동시에 해당하면 더 약한 확인(ask) 단계로 격하되는 결함을 발견·수정했습니다. - v0.2.6 — Windows 파괴적 명령 순서 결함: 윈도우에서 폴더·드라이브를 통째로 지우는 명령(
Remove-Item·del·erase·rd)이, 실무에서 흔한 명령어 순서(옵션이 경로 뒤에 오는 형태)에서는 못 알아채던 결함을 발견·수정했습니다. - v0.2.7 — 키 노출·심볼릭링크 결함 2건: 비밀키를 화면에 출력하는 걸 막는 규칙이 개발자가 가장 흔히 쓰는 코드 형태를 놓쳤고, 바로가기(심볼릭 링크) 생성을 막는 규칙이 결합된 옵션(강제+심볼릭을 함께 쓰는 형태)을 놓치던 결함 2건을 발견·수정했습니다.
- v0.2.8 — 노트북 파일 키 노출 검사 완전 누락(가장 심각): 위 3건은 "보호가 약해지는" 수준이었지만, 이 건은 보호 자체가 아예 작동하지 않던 경우였습니다. Jupyter 노트북(.ipynb) 파일을 편집하는 기능에서 API 키 같은 비밀값을 직접 적어도 전혀 걸러지지 않았습니다. Claude Code 공식 도구 명세를 직접 대조해 원인(내용을 전달하는 필드명이 다름)을 정확히 찾아 수정했습니다.
- 검증: 4건 모두 수정 전 재현 → 수정 후 자동 테스트 통과(최종 138개 테스트 전부 통과, 0건 실패) → 관련 없는 기능이 영향받지 않았는지 재확인까지 마쳤습니다.
📄 2026-08-21 — F8 나머지 답변 반영 · 라이선스 실사 확인 · 안전 경고 누락 수정 (v0.2.1~v0.2.4)
- F8(쉬운 모드) 내부 자체 빈틈 전부 해소: 2번 섹션이 사용자에게 던지는 3개 선택지("말투를 모르겠다"·"화면 이해가 안 된다"·"잘못될까 봐 무서워요") 중 답이 비어 있던 나머지를 전부 채웠습니다. 이후 "더 늘리지 말고 여기서 멈추자"고 판단해 F8 확장을 의도적으로 중단했습니다(근거 없는 확장은 과설계로 판단).
- 차용 오픈소스 라이선스 실사 확인: 내부 리서치 문서가 "직수입"·"복붙"이라 표시해둔 참고 저장소 4곳(anthropics/skills·wshobson/agents·OpenHarness·claude-code-harness)의 실제 라이선스를
ghCLI로 직접 조회했습니다. 3곳은 MIT(GPL/AGPL 오염 0건 확정), anthropics/skills는 LICENSE 파일 자체가 없다는 걸 확인했습니다. 새THIRD_PARTY_NOTICES.md에 MIT 3곳의 원문 저작권 고지를 정리해 추가했습니다. commands/start.md안전 경고 누락분 발견·수정: 자연어로 자동 발동되는skills/start/SKILL.md엔 "자동승인(bypass) 모드에서 안전 확인이 조용히 통과된다"는 경고 문단이 있는데,/sodam-agentic:start를 직접 실행하는 경로(commands/start.md)에만 이 문단이 빠져 있던 걸 발견해 추가했습니다.- 검증: 수정할 때마다 자동 테스트 126 PASS/0 FAIL·구조 검증 PASS 14/WARN 1/FAIL 0을 재확인하고, 회귀가 없음을 확인한 뒤에만 반영했습니다.
🆕 2026-08-13~15 — 게이트 1 재정의 + 주 사용자 정정 + F8(쉬운 모드) v1 착수
- 게이트 1 재정의: Codex 확인창 실측(④)은 "실제로 Codex를 쓰기 시작하는 시점까지 조건부 보류"로 재분류했습니다(지금은 100% Claude Code로만 쓰고 있어서, 검증 안 된 Codex 경로가 실제로 노출될 위험이 없기 때문입니다). 게이트 1은 이제 사실상 F2/F3 배너 실측(③) 하나만 남았습니다 — 여전히 미확인 상태입니다.
- 주 사용자 정정: 이전에 "친한 지인이 이미 쓰고 있다"고 적었던 내용을, 사용자 본인이 직접 "주 사용자는 나 혼자"라고 정정했습니다. 그에 따라 "지인에게 물어봐서 확인을 대신한다"는 경로는 철회하고, 원래 방식(본인이 평소 쓰면서 직접 확인)으로 되돌렸습니다.
- F8(쉬운 모드) v1 착수:
/sodam-agentic:f8-easy신설 — F1 온보딩보다 한 단계 더 쉬운 비유로 "AI에게 일 시키는 4단계"를 다시 설명해주는 추가 설명 계층입니다. 계획(F2)·검토(F3) 같은 안전 절차를 대신하거나 건너뛰지 않습니다. 원래는 게이트 1이 먼저 닫혀야 시작하는 기능이었는데, 사용자가 "지금 바로 진행하기"라고 직접 승인해 게이트가 닫히기 전에 먼저 착수했습니다. - 안전 코드는 F8을 아예 모르게 만듦:
hooks/guard.mjs·hooks/delegate.mjs(진짜 위험을 막는 코드) 안에는 F8 관련 코드가 단 한 줄도 없습니다. "설정으로 꺼서 확인"하는 대신, 두 파일의 소스 코드 안에 F8 관련 단어가 아예 존재하지 않는지를 자동 테스트가 직접 검사하도록 만들었습니다 — 안전장치가 F8의 존재 자체를 모르니, F8을 켜고 끄고는 안전 수준에 영향을 줄 수가 없습니다. - 엉뚱한 입력값 테스트: 깨진 데이터, 빠진 정보, 5만 글자짜리 긴 명령어 등 여섯 가지 이상한 입력을 안전장치에 직접 넣어봤습니다. 전부 오류 없이 안전하게 처리됐습니다(위험한 내용은 아무리 길어도 정확히 걸러냈고, 그 외에는 안전하게 통과시켰습니다).
- 검증: 자동 테스트 100건 전부 통과(0건 실패). 안전장치 파일(
hooks/guard.mjs·hooks/delegate.mjs·hooks/hooks.json)은 이번 작업으로 단 한 글자도 바뀌지 않았음을 직접 대조해 재확인했습니다.
🔍 2026-08-04 — 현재 상태 점검 (Phase 3 진입 게이트 현황, 코드 변경 없음)
CHECKPOINT.md(내부 개발 메모)를 기준으로, Phase 3(무경험자 모드·MCP 큐레이션) 착수 전 통과해야 하는 게이트 1(사람의 실제 라이브 확인 5개 항목)의 현재 진행 상황을 있는 그대로 옮깁니다:
- ①
.mcp.json자동 차단 — 확인됨(2026-08-04 라이브로 2회 재현 + 안전 기록에서도 확인). - ② 폴더 통째 삭제 차단 — 자동 테스트(로컬 자가검증)로는 이미 확인됐지만, 사람이 실제로 "삭제해줘"라고 시켜서 화면으로 보는 확인은 아직 안 됨(AI가 도구를 시도하기 전에 스스로 다시 물어보는 경우가 많아, 정작 안전장치의 차단 코드 자체가 시험될 기회가 잘 안 생김).
- ③ 계획 먼저(F2)·변경점 검토(F3)의 화면 표시(
🚀/🔍) — 여러 세션에서 시도했지만 아직 한 번도 목격되지 않음(스킬은 "부탁"이라 강제할 수 없다는 플랫폼 한계 때문일 가능성이 큼). - ④ Codex에서 확인(ask) 창이 실제로 뜨는지 — Codex를 쓰는 경우에만 해당하는 선택 확인이라 아직 시도 안 됨.
- ⑤ 형제 플러그인(SoDamLoop)의 오래된 상태 파일 문제 — 이 컴퓨터에서 5주 넘게 "실행 중" 상태로 방치된 파일이 하나 발견되어, 그것이 안전 파일 자체 수정 보호와 관련 있을 가능성이 제기됐고 아직 정리되지 않음(사람이 직접 정리해야 하는 항목).
요약: 안전 기능 자체(코드·자동 테스트)는 계속 정상 동작 중이지만, 위 5개 중 아직 4개는 "사람이 실제 화면으로 본 확인"이 남아 있습니다. 안전장치가 실제로 안 막는다는 뜻이 아니라, 확인 절차가 아직 안 끝났다는 뜻입니다.
🛠 2026-08-03 — F6 안전 기록 누락 결함 조사·재시도 로직 추가
- 실사용 중
.mcp.json차단(deny)이 화면엔 정상적으로 떴는데, 안전 기록 파일(safety-log.jsonl)에는 그 순간이 기록되지 않는 결함을 발견했습니다. 원인 후보로 "여러 소담 형제 프로젝트가 같은 로그 파일에 동시에 기록을 시도하다 생기는 Windows 파일잠금 경합"을 지목했습니다(완전히 증명되진 않았지만 근거는 있음). hooks/guard.mjs의 로그 기록 함수에 짧은 재시도(최대 3회, 회당 20ms)를 추가해 일시적인 경합을 흡수하도록 했습니다. 그래도 실패하면 예전처럼 조용히 포기합니다 — 로그 기록 실패가 차단·확인 판정 자체에는 절대 영향을 주지 않습니다(이건 감사 기록만의 문제이지 안전 기능의 결함이 아닙니다).- 로컬 자가검증(
hooks/_selftest.mjs) 98 PASS / 0 FAIL로 회귀 없음을 확인했습니다. LIVE_TEST_GUIDE.md의 "위험한 명령을 실제로 시켜보는" 테스트 문구를 "확인하지 말고 바로 실행해줘"처럼 더 명확하게 다듬었습니다(AI가 스스로 되묻느라 안전장치의 차단 코드 자체가 시험되지 못하는 경우가 있었기 때문).
🧪 2026-08-03 — 첫 실사용 라이브 테스트 결과
- 실제 사용 화면에서 처음으로 종합 테스트를 진행했습니다.
.mcp.json차단(deny)과 작업폴더 밖 쓰기 확인(ask)이 실제로 정상 작동함을 확인했습니다. - 재미있는 발견: AI가 "이번엔 확인창이 안 떴다"고 스스로 잘못 보고한 사례가 있었는데, 실제 기록 파일을 대조해보니 확인창은 정상적으로 떴던 것으로 확인됐습니다(확인창은 화면 팝업이라 대화 기록 텍스트만으로는 AI 자신도 못 볼 수 있다는 뜻입니다).
- 폴더 통째 삭제 차단·설정파일 차단은 AI가 위험한 명령을 실행하기도 전에 스스로 다시 물어보는 바람에 이번에도 실제 차단 코드까지는 도달하지 못했습니다.
🔐 2026-08-02 — 안전 기록 저장 위치를 공식 영구 데이터 경로로 안전하게 전환 시도
- 안전 기록(
safety-log.jsonl)의 저장 위치를 기존~/.sodamagentic에서, Claude Code 플러그인 공식 데이터 경로(${CLAUDE_PLUGIN_DATA})로 옮기는 작업을 했습니다. 이 경로를 쓰면 업데이트·재설치에도 데이터가 살아남고, 플러그인을 완전히 제거하면 자동으로 함께 정리되는 장점이 있습니다. - 회귀 위험 없이 설계했습니다: 새 경로가 실제로 전달되면 그걸 쓰고, 전달이 안 되거나 이상하면(Codex 등) 예전처럼
~/.sodamagentic을 그대로 씁니다. 즉 최악의 경우에도 지금까지와 동일하게 동작합니다. ⚠️ 정직한 한계: 이 새 경로가 실제 설치 환경에서 문자열 그대로 잘 전달되는지는 이 패치 시점까지 라이브로 확인되지 않았습니다. 최근 확인 결과 여전히 예전 위치(~/.sodamagentic)에 기록되고 있는 것으로 보이며, 어느 위치가 실제로 쓰이는지는 재설치 후 다시 확인이 필요합니다.
🔴 2026-08-02 — Codex 안전 패리티의 숨은 결함 발견·수정 (보안)
- 그동안 "완료"로 표시돼 있던 Codex 쪽 안전 기능에서 실제 결함을 발견했습니다: 같은 컴퓨터에 Claude Code용 형제 플러그인(SoDamHarness)이 설치돼 있으면, Codex에서 실행 중인데도 "형제가 살아있다"고 잘못 판단해 일부 보호(민감 위치 검사 등)를 형제 쪽에 넘겨버리는데, 정작 Codex 설치 스크립트는 그 형제의 훅을 Codex에 등록하지 않기 때문에 그 위임을 아무도 받아주지 않는 "허공 위임" 상태였습니다.
hooks/guard.mjs가 자기 파일 경로를 보고 "지금 내가 Codex용으로 배포된 사본인지"를 스스로 판별해, Codex 배포본이면 형제 위임을 절대 하지 않고 항상 전체 안전 폴백을 쓰도록 고쳤습니다(이 판별 로직을 코드에서는IS_CODEX_DEPLOY라고 부릅니다).- 이 결함을 재현하는 회귀 테스트 3건을 추가해 로컬 자가검증 95 PASS를 확인했습니다.
🔐 2026-08-02 — settings.json 보호 항목을 11개로 확장 (보안)
.claude/settings.json에서 확인(ask)이 아니라 즉시 차단(deny)해야 하는 "민감 항목" 목록을 공식 문서와 재대조해 4개(mcpServers·enableAllProjectMcpServers·permissions·hooks)에서 11개로 확장했습니다. 새로 추가된 것:enabledMcpjsonServers·disabledMcpjsonServers·enabledMcpServers·disabledMcpServers(MCP 서버 자동 승인 관련),disableAllHooks(안전 훅 전체를 끄는 스위치),env(AI 통신 경로를 몰래 바꿀 수 있는 환경변수),apiKeyHelper(인증 방식을 바꿀 수 있는 설정).- 로컬 자가검증 92 PASS로 회귀 없음을 확인했습니다.
🛡 2026-07-27 — 보안 집중 강화 4건: settings.json · 마켓플레이스 이름 · .mcp.json
.claude/settings.json의 민감 변경(당시 4개 항목)을 확인(ask)에서 즉시 차단(deny)으로 승격했습니다. 지금까지는 내용과 무관하게 항상 확인창만 떴는데, AI 안전장치 자체를 무력화할 수 있는 가장 위험한 변경이 확인창 하나로만 방어되고 있었기 때문입니다.- 같은 민감 항목을 "새로 추가"하는 경우뿐 아니라 "삭제해서 보호를 없애는" 경우도 함께 차단 대상에 넣었습니다.
- 마켓플레이스 이름 충돌을 발견·수정했습니다. 실사용 테스트 중 설치 자체가 실패하는 원인을 추적한 결과, 이 플러그인의 마켓플레이스 이름(
sodam)이 다른 형제 플러그인과 겹쳐 있었던 것을 발견해sodam-agentic으로 변경했습니다(지금 이 문서의 설치 명령이 그 결과입니다). .mcp.json(진짜 MCP 서버 실행 설정 파일)의 보호 공백을 발견·보완했습니다.mcpServers라는 민감 설정값이 실제로는.claude/settings.json이 아니라.mcp.json이라는 완전히 다른 파일에만 존재한다는 것을 공식 문서로 확인했습니다. 즉 1번 항목의 보호는 그동안 존재하지도 않는 위치만 지켜보고 있었던 셈이라, 이제.mcp.json은 내용과 무관하게 항상 차단됩니다.
로컬 자가검증이 67건 → 85건까지 늘었고 전부 통과했습니다.
🚀 2026-07-26 — 계획·검토 발동 표시(배너) 추가
- 계획 먼저(F2)·변경점 검토(F3)가 실제로 발동했는지 화면에서 바로 알 수 있도록, 발동 시 응답 맨 위에
🚀 소담 — 계획 먼저/🔍 소담 — 변경점 검토문구를 출력하도록 스킬 지시문에 추가했습니다(로직 변경 없음, 문서 지시문만 추가).
✅ 2026-07-18 — 슬래시 명령 짧은형 전환 + Harness 감지 경로 오탐 수정
/sodam-agentic:sodam-agentic-start같은 긴 이름을 지금의/sodam-agentic:start로 단축했습니다(4개 명령 전부).- "계획 먼저"·"검토" 기능을 자동 발동 외에 직접 명령으로도 부를 수 있게
commands/plan.md·commands/review.md를 새로 추가했습니다. - 실제 Windows Claude Code 설치 경로와 형제 플러그인 감지 로직이 달라서 생기던 오탐을 수정했고, 그 과정에서 "작업폴더 밖 새 파일 쓰기 확인"이 형제에게 위임했다가 조용히 빠지고 있던 실제 보호 공백도 함께 발견해 보완했습니다(이 항목은 이제 형제 유무와 무관하게 항상 자체 확인합니다).
🔧 2026-07-16~17 — 출처 표시 추가 + 형제 플러그인 충돌 대비
- 확인(ask)·차단(deny) 메시지 앞에
[소담 에이전틱]이라는 출처 표시를 추가했습니다. 형제 플러그인(SoDamHarness)과 동시에 설치돼 있으면 안전 메시지가 동시에 뜰 수 있는데, 어느 플러그인이 막은 건지 사용자가 바로 구분할 수 있게 하기 위함입니다. - 진단 도구(
family-health.mjs)가 오래된 메모를 실시간 사실처럼 보여주던 문제를 수정했습니다.
✅ 2026-07-15 — F6 안전 기록 + F7 Codex 안전 패리티 구현
- F6. 확인(ask)·차단(deny) 판정마다 안전 기록 파일에 자동 기록하는 기능을 추가했습니다. 비밀값은 저장 전 자동으로 마스킹됩니다.
/sodam-agentic:log로 조회할 수 있습니다. - F7. Codex CLI의 실제 훅 스키마가 Claude Code와 사실상 동일함을 공식 문서로 확인한 뒤, 새 로직을 따로 만들지 않고 같은 안전 훅(
hooks/guard.mjs)을 Codex에도 그대로 등록하도록 설치 과정을 확장했습니다. - 로컬 자가검증이 44건 → 54건으로 늘었습니다.
🛡 2026-07-12~14 — 실사용 검증으로 실제 보호 공백 다수 발견·보완
- "작업폴더 밖에 쓰지 못하게 막는" 규칙이 일부 상황에서 빠져 있던 것을 보강했습니다.
- 바로가기(심볼릭 링크·정션)를 만드는 명령을 확인 대상에 포함했고, 경로 중간에 링크가 끼어 있어도 감지하도록 검사 로직을 보강했습니다.
- 출처를 확인하지 않은 외부 코드를 곧바로 실행하는 패턴(예:
curl | bash)을 막는 안전장치를 새로 추가했습니다 — 그전까지는 전혀 검사하지 않던 부분입니다. - 도구 종류(파일 쓰기 도구 vs 셸 명령)에 따라 경로 검사 적용 여부가 달라지던 불일치를 발견해 통일했습니다.
- 회귀 테스트가 22건 → 44건으로 확대됐고 전부 통과했습니다.
✅ 2026-07-11 — 실사용 화면에서 안전장치가 실제로 작동함을 최초 확인
- 코드 시뮬레이션(자가검증)만이 아니라, 실제 사용 화면에서 위험해 보이는 명령을 시도해 정말로 막히는지 처음으로 눈으로 확인했습니다.
- 여러 작업을 연속으로 시키면 전혀 위험하지 않은 평범한 명령까지 "위험하다"며 잘못 막던 오탐을 발견·수정했습니다.
🔧 2026-07-07 — 안전 폴백 상시 활성화 + 문서 전면 개정
- 안전 폴백(F4)이 특정 조건에서 잠들어 있을 수 있던 결함을 찾아 수정했습니다 — 이제 설치되면 항상 켜집니다.
- 되돌릴 수 없는 치명 명령은 형제 플러그인(SoDamHarness) 설치 여부와 무관하게 항상 차단하도록 강화했습니다(이중 안전장치).
- 자동 승인 모드에서는 확인창이 조용히 통과된다는 한계를 온보딩 안내에 명시했습니다.
📦 [0.1.0] — 2026-06-28 (최초 배포, Phase 1 MVP)
- F1 한국어 온보딩(
/sodam-agentic:start) — 계획→실행→검토→안전 4단계 안내. - F2 계획 먼저 스킬 — 코드 전 무엇을·왜·완성기준 명시적 승인.
- F3 변경점 쉬운 말 검토 스킬 + 위임 에이전트(
easy-reviewer). - F4 안전 훅 — 최소 폴백 4종 차단, Harness 위임, fail-closed.
- F5 두 도구(Claude Code + Codex) 설치 지원.
LICENSE(Apache-2.0)·NOTICE추가.
알려진 한계(당시): F2/F3 스킬은 "부탁"이라 강제할 수 없음, Codex에서는 F4 안전이 Claude Code보다 약함(이후 F7에서 보완).
개발 폴더(원본): D:\AI_Dev_Work\2026y\26y_06m_26d_SoDam-Agentic-Eng
GitHub(인터넷): https://github.com/sodam-ai/SoDam-Agentic-Eng (공개)
| 무엇 | 위치 |
|---|---|
| 플러그인 설명 파일 | .claude-plugin/plugin.json, .claude-plugin/marketplace.json |
| 온보딩 명령 | commands/start.md (/sodam-agentic:start) |
| 계획·검토·기록 명령 | commands/plan.md, commands/review.md, commands/log.md |
| 자동 발동 스킬 | skills/start/SKILL.md, skills/plan/SKILL.md, skills/review/SKILL.md |
| 쉬운 모드(F8) | skills/f8-easy/SKILL.md(자동 발동), commands/f8-easy.md(수동 /sodam-agentic:f8-easy) |
| 검토 보조 에이전트(읽기 전용) | agents/easy-reviewer.md |
| 안전장치(훅) | hooks/hooks.json(배선표), hooks/guard.mjs(판정 로직), hooks/delegate.mjs(형제 감지) |
| 안전 규칙(데이터) | data/agentic-rules.json |
| 구조 점검 도구 | scripts/validate.mjs, scripts/family-health.mjs |
| Codex 설치기 | codex/install.mjs |
| AI 공유 지침 | AGENTS.md(Claude Code·Codex 공용), CLAUDE.md(포인터) |
| 6형제 협업 문서 | docs/family-synergy.md |
| 실사용 테스트 절차서 | LIVE_TEST_GUIDE.md |
| 법률 문서 | LICENSE(Apache-2.0 전문), NOTICE(저작권 고지), THIRD_PARTY_NOTICES.md(참고 오픈소스 출처 고지) |
| 변경 이력(원본) | CHANGELOG.md |
| 안전 기록 파일(내 컴퓨터, F6) | ~/.sodamagentic/safety-log.jsonl (Windows에서는 C:\Users\<사용자>\.sodamagentic\safety-log.jsonl) — 현재 확인된 실제 사용 위치입니다. 공식 영구 데이터 경로(${CLAUDE_PLUGIN_DATA}, 문서상 위치는 ~/.claude/plugins/data/sodam-agentic/safety-log.jsonl)로 옮기는 작업이 코드에는 들어가 있지만, 실제로 그 경로가 적용됐는지는 아직 라이브로 확정되지 않았습니다 — /sodam-agentic:log 명령은 이 두 위치를 모두 확인합니다 |
| Codex 훅 등록 파일 | 내 프로젝트의 .codex/hooks.json (설치 시 자동 생성·병합) |
| 설치 후 저장 위치(Claude Code 관리) | C:\Users\<사용자>\AppData\Roaming\claude-code\plugins\ |
비유: AI는 공장의 기계이고, 당신은 공장을 설계하는 사람입니다. 검토는 건설 감리사가 완공된 건물을 점검하는 것과 같습니다.
[시작] /sodam-agentic:start → 안전 켜짐 확인 + 4단계 안내
│
▼
[계획 먼저] "만들어줘" → AI가 계획(무엇을·왜·완성기준) 제시 → 당신이 "네/진행"으로 승인
│
▼
[실행] AI가 작업 ──(위험한 시도가 있으면)──▶ [안전] 자동 차단 또는 확인
│
▼
[검토] 무엇을·왜·위험은? 요약 → 당신이 최종 판단 → 완료
핵심 원칙: "AI가 다 알아서"가 아니라, 사람이 운전석에 앉습니다.
발동 확인법: 계획 먼저(F2)가 실제로 작동하면 응답 맨 위에
🚀 소담 — 계획 먼저가, 변경점 검토(F3)가 작동하면🔍 소담 — 변경점 검토가 뜹니다. 이 문구가 안 보이면(다른 스킬에 밀려 자동발동이 안 될 때가 있습니다) 그 자리에서 "계획 먼저 보여줘" / "검토해줘"라고 직접 요청하면 됩니다.
이 플러그인은 서버·DB·로그인이 없는, 순수 로컬 도구입니다. 소담 6형제 플러그인 패밀리(SoDamHarness·SoDamLoop·SoDamContext·SoDamAgentic·SoDamPrompt·SoDamReverse) 중 진입점(계획·검토) 역할을 맡습니다 — 안전·백업은 SoDamHarness, 반복 작업은 SoDamLoop 소유이며, 이 플러그인은 그 영역을 중복 구현하지 않고 "형제가 있으면 위임"하는 방식으로 협업합니다.
| 구성요소 | 파일 | 역할 |
|---|---|---|
| 매니페스트 | .claude-plugin/plugin.json, marketplace.json |
Claude Code에 "이 폴더가 플러그인"이라고 알려주는 설명서 |
| 온보딩 (F1) | commands/start.md, skills/start/SKILL.md |
/sodam-agentic:start — 4단계 안내 |
| 계획·검토 (F2·F3) | skills/plan/·skills/review/(자동 발동) + commands/plan.md·commands/review.md(수동 호출) |
새 작업 요청·변경 완료 시 자동 발동 + 직접 호출도 가능 |
| 쉬운 모드 (F8) | skills/f8-easy/SKILL.md(자동) + commands/f8-easy.md(수동) |
F1보다 한 단계 더 쉬운 설명 계층. guard.mjs·delegate.mjs를 전혀 참조하지 않도록 설계(자동 테스트가 두 파일 소스 코드에서 F8 관련 단어를 검사해 보장) — 안전 절차(F2·F3)를 대신하거나 건너뛰지 않음 |
| 검토 보조 에이전트 | agents/easy-reviewer.md |
변경이 많을 때 F3가 위임하는 읽기 전용 서브 AI(Read·Grep·Glob만 사용) |
| 안전 훅 (F4) | hooks/hooks.json(배선표) + hooks/guard.mjs(판정 로직) + hooks/delegate.mjs(형제 감지) |
Bash·PowerShell·Write·Edit·MultiEdit·NotebookEdit 실행 직전에 항상 개입 |
| 안전 규칙 데이터 | data/agentic-rules.json |
코드 수정 없이 조정 가능한 규칙 값(위험 패턴·계획 생략 기준 등) |
| 안전 기록 (F6) | hooks/guard.mjs의 decide() 내부 로직 + commands/log.md |
확인(ask)·차단(deny) 판정마다 로그 파일에 기록, 명령으로 조회 |
| Codex 지원 (F5·F7) | codex/install.mjs |
마켓플레이스가 없는 Codex용 별도 설치기(스킬·훅을 파일로 복사, 새 안전 로직을 만들지 않고 같은 guard.mjs를 재사용) |
| AI 공유 지침 | AGENTS.md, CLAUDE.md |
Claude Code·Codex 양쪽이 함께 읽는 규칙 파일 |
Claude Code가 도구(Bash·PowerShell·Write·Edit 등)를 실행하려는 순간
│
▼
hooks/guard.mjs 가 먼저 판정 (PreToolUse = "실행 직전")
│
├─ 안전(safe) → 그냥 통과(로그도 안 남김)
├─ 확인 필요(ask) → "정말 진행할까요?" 질문
├─ 위험(deny) → "막았어요" (형제 SoDamHarness가 살아있으면 겹치는 항목은 위임)
└─ 치명(catastrophic) → "막았어요" (형제 유무와 **무관하게 항상** 자체 차단)
hooks/delegate.mjs의isHarnessAlive()가 형제 플러그인 SoDamHarness의 존재(설치 위치·최소 버전·헬스체크 3조건)를 확인합니다.- Harness가 살아있으면 "겹치는" 위험(민감 경로 쓰기·심볼릭 링크 우회 등)은 Harness에 넘겨 확인창이 두 번 뜨지 않게 합니다.
- 단, 되돌릴 수 없는 치명 명령·
.mcp.json·작업폴더 밖 쓰기 확인·.claude/settings.json검사는 Harness 설치 여부와 무관하게 이 플러그인도 항상 자체적으로 수행합니다 — 형제가 없거나, 형제가 그 보호를 갖고 있지 않을 때를 대비한 이중 안전장치입니다. - Codex에서 실행 중일 때는 형제 위임 자체를 하지 않습니다.
guard.mjs가 자신이 Codex용으로 복사된 사본인지(.agents/hooks/guard.mjs경로) 스스로 판별해, Codex에서는 형제가 감지돼도 항상 전체 폴백을 씁니다 — Codex 설치기가 형제의 훅까지 Codex에 등록해주지는 않기 때문에, 위임을 시도해봤자 아무도 받아주지 않는 상황을 막기 위함입니다.
- 이 플러그인이 읽는 것: Claude Code(또는 Codex)가 실행하려는 도구 이름과 인자(실행할 명령어 문자열, 쓰려는 파일 경로·내용)뿐입니다. 이 정보는 표준입력(stdin)으로 훅에 전달됩니다. 그 외 파일 내용이나 대화 전체를 따로 들여다보지 않습니다.
- 이 플러그인이 절대 하지 않는 것: 자체 네트워크 요청(외부 서버로 전송) · API 키·비밀번호·토큰 저장 또는 기록 · 외부 코드 자동 실행 ·
eval/동적 코드 실행. (자기보안 자가검증 결과 0건)
| # | 무엇을 검사하나 | 위험할 때 | 애매할 때 |
|---|---|---|---|
| ① | 위험·치명 명령(폴더 통째 삭제, format, 포크폭탄, 디스크 장치에 직접 쓰기, 출처 미확인 외부 코드를 곧바로 실행하는 패턴 등) |
차단(deny) — 치명 등급은 형제 유무와 무관하게 항상 차단 | 파일 하나만 지우는 것처럼 비교적 가벼운 위험은 확인(ask) |
| ② | API 키·비밀값 노출(sk-ant-... 패턴, .env를 외부로 전송하는 명령, ANTHROPIC_BASE_URL 변조, echo $KEY 류) |
차단(deny) | .env를 그냥 화면에 읽기만 하는 것(cat .env 등)은 확인(ask) |
| ③ | 작업 폴더 밖의 민감한 위치(사용자 홈 폴더 자체, ~/.ssh·~/.aws·~/.claude·~/.codex·~/.gnupg·~/.config, C:\Windows·C:\Program Files 등 시스템 폴더, 드라이브 루트, 경로 중간의 심볼릭 링크·정션) |
차단(deny) | 그 외 작업폴더 밖 위치에 새로 쓰는 것은 (민감 위치가 아니어도) 항상 확인(ask) |
| ④ | .claude/settings.json·settings.local.json의 민감 항목(총 11개: mcpServers·enableAllProjectMcpServers·permissions·hooks·enabledMcpjsonServers·disabledMcpjsonServers·enabledMcpServers·disabledMcpServers·disableAllHooks·env·apiKeyHelper)을 추가·수정·삭제 |
차단(deny) | 그 외 일반 설정 변경(예: 모델명 변경)은 확인(ask) |
+ 항상 별도로 차단되는 것: .mcp.json(Claude Code가 폴더를 열 때 자동 실행할 MCP 서버 목록을 정의하는 파일)은 내용과 무관하게 항상 통째로 차단됩니다. 이 파일이 원치 않게 바뀌면 다음에 이 폴더를 열 때 낯선 프로그램이 자동으로 실행될 수 있기 때문입니다. 정말 필요하면 사용자가 직접 편집기로 열어 수정해야 합니다.
💡 주의:
enabledMcpServers·disabledMcpServers두 항목은 실제로는.claude/settings.json이 아니라 별도 파일(~/.claude.json)에 저장되는 값이라는 것을 공식 문서로 확인했습니다. 이 훅은.claude/settings.json안에서만 이 두 이름을 감시하므로 지금은 발동 조건이 성립하지 않습니다(안전 쪽으로 무해하니 목록엔 그대로 남겨뒀습니다) — 정확성을 위해 정직하게 밝힙니다.
형제 플러그인 SoDamHarness가 설치·최소버전·헬스체크 3조건을 모두 만족하며 살아있으면, ③의 "민감 위치 차단"·심볼릭 링크 우회 검사처럼 겹치는 항목은 Harness에 위임해 확인창이 두 번 뜨지 않게 합니다. 단, ①의 치명 명령·.mcp.json·작업폴더 밖 쓰기 확인·④의 settings 검사는 형제 유무와 무관하게 이 플러그인도 항상 자체 수행합니다(이중 안전장치, Codex에서는 위임 자체를 아예 하지 않습니다).
안전 훅이 확인(ask)·차단(deny) 판정을 내릴 때만 {판정, 대상, 이유, 시각} 형태로 한 줄씩 기록을 남깁니다. 안전하게 통과한 작업은 기록하지 않습니다(로그 비대화 방지). 대상 문자열에 비밀값 패턴(API 키 등)이 있으면 저장 전 자동으로 [REDACTED]로 가려집니다. 여러 프로젝트가 동시에 기록을 시도할 때를 대비해 짧은 재시도(최대 3회) 로직이 있지만, 그래도 실패하면 조용히 포기합니다 — 기록 실패가 안전 판정 자체에는 절대 영향을 주지 않습니다. 이 기록은 외부로 전송되지 않고 내 컴퓨터에만 남습니다. 조회는 /sodam-agentic:log.
| 단계 | 예시 상황 | 실제로 뜨는 안내(요약) |
|---|---|---|
| ✅ 안전(통과) | 새 파일 만들기, 일반 설정값 변경 같은 평범한 작업 | (아무 메시지 없이 그냥 진행) |
| ❓ 확인(ask) | 파일 하나 삭제, 작업폴더 밖 쓰기 | "[소담 에이전틱] 되돌리기 어려운 작업이에요… 정말 진행할까요?" |
| ⛔ 차단(deny) | 비밀 값 노출 우려가 있는 작업 | "[소담 에이전틱] API 키·비밀값이 노출될 수 있는 작업이라 막았어요…" |
| ⛔ 차단(deny) | 폴더 통째 삭제 | "[소담 에이전틱] 폴더를 통째로 지우는 작업은 안전하게 막았어요…" |
| ⛔ 차단(deny) | .claude/settings.json의 민감 항목을 바꾸거나 지우기 |
"[소담 에이전틱] AI 안전장치 자체를 바꿀 수 있는 항목이라 막았어요…" |
| ⛔ 차단(deny) | .mcp.json을 새로 만들거나 바꾸기 |
"[소담 에이전틱] 이 파일은 Claude Code가 자동 실행할 MCP 서버를 정의하는 곳이라 막았어요…" |
| ⛔ 차단(항상, 치명) | 되돌릴 수 없는 파괴적 명령, 출처 미확인 외부 코드를 곧바로 실행하는 패턴 | "[소담 에이전틱] 되돌릴 수 없는 위험한 명령이라 막았어요…" |
[소담 에이전틱]접두사는 형제 플러그인(SoDamHarness 등)과 동시 설치돼 훅이 함께 발동해도 어느 플러그인이 막았는지 바로 구분되도록 붙인 출처 표시입니다. 자연어로 부탁하든, 명령어를 직접 지정하든 동일한 기준으로 검사합니다.
이 저장소의 코드 주석에도 명시돼 있듯, "위험 패턴은 초안이며 모든 위험을 100% 잡지 못합니다." 안전 훅은 "되돌릴 수 없는 위험은 막고, 나머지는 확인받는" 정도이며, 최종 판단은 항상 사람이 합니다. 화면 아래 자동 승인(auto-accept / bypass permissions) 모드가 켜져 있으면 확인창이 조용히 통과되어 이 보호가 약해집니다 — 안전하게 쓰려면 Shift+Tab으로 "매번 물어봄" 모드를 권장합니다(훅은 이 모드를 스스로 감지할 수 없습니다).
| 증상 (이렇게 보임) | 왜 (원인) | 이렇게 (해결) |
|---|---|---|
| 깔았는데 아무 일도 안 일어남 | /init 안 함 / 온보딩 안 읽음 |
/sodam-agentic:start로 상태부터 확인 |
/sodam-agentic 쳐도 명령이 안 뜸 |
설치 안 됨 또는 마켓플레이스 이름 오타 | /plugin install sodam-agentic@sodam-agentic 다시 (반드시 @sodam-agentic) |
| 설치할 때 "권한 없음 / 접근 불가" | 저장소는 공개 상태라 계정 권한 문제일 가능성은 낮음 — 인터넷 연결 또는 주소·이름 오타 문제일 수 있음 | 인터넷 연결 확인 + /plugin marketplace add https://github.com/sodam-ai/SoDam-Agentic-Eng 주소가 정확한지 재확인 |
| "Node가 없다"고 나옴 | Node.js 미설치 | §3 따라 Node.js 18+ 설치 후 재시도 |
한글이 □□□로 깨짐 |
글자 표시(폰트) 문제 | 터미널·에디터의 UTF-8 설정 확인, 화면 캡처해서 문의 |
| 계획 없이 바로 코드부터 짬 | 다른 스킬에 밀림(F2는 "부탁"이라 강제 아님) | 정상적으로 일어날 수 있음 — 그 자리에서 "계획 먼저 보여줘"라고 직접 요청 |
| 위험 명령이 안 막힘 | 안전 훅 미작동 또는 자동승인 모드 | 자동 승인(auto-accept/bypass) 모드인지 먼저 확인(§12), 아니면 캡처해서 문의 |
| 확인창이 너무 자주 뜸 | 여러 안전장치(형제 플러그인 포함)가 겹침 | 정말 위험한 것만 뜨도록 data/agentic-rules.json으로 조정 가능 |
| 명령어가 옛 이름으로 보임 / 방금 고친 게 반영 안 됨 | 설치본(캐시)이 최신이 아님 | /plugin uninstall sodam-agentic@sodam-agentic → /plugin install sodam-agentic@sodam-agentic → /reload-plugins (반드시 이 순서로, marketplace update만으로는 부족합니다) |
| 비밀번호·API 키를 넣어도 되나요? | — | 절대 넣지 마세요. 본인 환경(.env 등)에만 보관하고, 훅이 감지하면 즉시 차단합니다 |
| 지우고 싶어요 / 업데이트 후 이상해요 | 제거·업데이트 | §16 제거 방법 참고 |
| 지난번에 뭐가 막혔는지 기억이 안 남 | — | /sodam-agentic:log 명령으로 조회(막힘·확인만 기록되고, 안전하게 통과한 작업은 기록 안 됨) |
| Codex에서 확인(ask) 창이 안 뜨는 것 같음 | 아직 사람이 라이브로 확인하지 않은 부분 | Codex 자체의 /hooks 명령으로 등록 여부를 먼저 확인 후 캡처해서 문의 |
Q. 이거 정말 안전한가요? A. 아니요, "100% 안전"은 아닙니다. "되돌릴 수 없는 위험은 막고, 나머지는 확인받는" 정도입니다. 위험 패턴은 초안이라 모든 위험을 다 잡지 못한다는 것을 이 저장소 코드 주석에도 정직하게 적어뒀습니다. 최종 판단은 항상 사람이 합니다.
Q. 인터넷 연결이 항상 필요한가요? A. 설치할 때만 필요합니다. 설치가 끝난 뒤에는 이 플러그인 자체가 네트워크 요청을 보내지 않습니다(다만 Claude Code/Codex 본체가 AI 모델과 통신하는 것은 당연히 인터넷이 필요합니다).
Q. 돈이 드나요? A. 이 플러그인 자체는 무료(Apache-2.0) 라이선스입니다. 다만 Claude/Codex를 쓰는 비용(AI 모델 사용료)은 Anthropic·OpenAI 약관을 따로 따릅니다 — §15 라이선스 참고.
Q. Codex에서도 Claude Code와 똑같이 안전한가요? A. 같은 안전장치가 Codex에도 등록됩니다. 계획(F2)·검토(F3)·차단·안전 기록(F6)까지 같은 로직을 씁니다. 다만 Codex에서 "확인해도 될까요?" 창이 실제로 화면에 뜨는지는 아직 사람이 직접 확인하지 않았습니다 — 100% 동등하다고 단정하지 않고 정직하게 남겨둡니다.
Q. SoDamHarness(형제 플러그인) 없이 써도 되나요? A. 됩니다. Harness가 없으면 이 플러그인의 "최소 안전 폴백"이 전체 모드로 작동합니다. 다만 자동 백업·되돌리기 같은 더 강한 기능은 Harness가 있어야 합니다.
Q. 상업적으로 써도 되나요? A. 이 플러그인 자체는 Apache-2.0이라 상업 사용·재배포·서비스 운영 모두 가능합니다(NOTICE 파일 보존 조건). 단 Claude/Codex 모델 사용의 상업 조건은 각 제공사 약관을 확인하세요 — §15 라이선스.
Q. 막히거나 확인받은 기록을 나중에 다시 볼 수 있나요?
A. 됩니다. /sodam-agentic:log 명령으로 최근 기록을 쉬운 한국어로 볼 수 있습니다. 안전하게 통과한 작업은 기록되지 않고, 막히거나(deny) 확인받은(ask) 것만 남습니다. 기록은 내 컴퓨터에만 저장되고 어디로도 전송되지 않습니다.
Q. 제가 시킨 작업 내용이 어딘가로 전송되나요? A. 이 플러그인 자체는 네트워크 요청을 보내지 않습니다. Claude Code/Codex 자체가 AI 모델과 통신하는 것과는 별개입니다. 안전 기록(F6)은 전송이 아니라 내 컴퓨터 파일에 저장하는 것입니다.
Q. 다른 5개 형제 플러그인도 꼭 설치해야 하나요? A. 아니요. 이 플러그인 혼자서도 최소 안전으로 작동합니다. 다만 SoDamHarness와 같이 쓰면 안전이 더 강력해지고, SoDamLoop과 같이 쓰면 반복 작업이 가능해집니다.
Q. .mcp.json을 왜 무조건 막나요? 제가 진짜 MCP 서버를 추가하고 싶으면요?
A. 이 파일을 편집기로 직접(사람이 손으로) 여시면 됩니다. 이 플러그인이 막는 건 "AI가 자동으로 이 파일을 대신 바꾸는 것"만입니다.
Q. 계획(F2)·검토(F3)가 매번 뜨나요? A. 아직 "무조건 뜨게" 강제하는 기술적 장치는 없습니다(스킬은 AI가 지키는 "부탁"이라 다른 스킬에 밀릴 수 있습니다). 안 보이면 그 자리에서 "계획 먼저 보여줘" / "검토해줘"라고 직접 요청하면 됩니다.
Q. F8(쉬운 모드)이 뭔가요? 저한테 필요한가요?
A. F1 온보딩을 한 번 읽었는데도 여전히 "이게 다 무슨 소리인지 모르겠다" 싶을 때 쓰는, 한 단계 더 쉬운 설명입니다. "설명이 너무 어려워요" 같은 말을 하면 자동으로 뜨거나, /sodam-agentic:f8-easy로 직접 부를 수 있습니다. 설명만 더 쉬워질 뿐, 계획(F2)·검토(F3) 같은 안전 절차는 이 모드를 켜든 끄든 항상 똑같이 작동합니다.
⚠️ 이 절은 법률 자문이 아닙니다. 아래는 일반 안내이며, 실제 배포·상업 사용 전에는 본인 책임으로 전문가(변호사 등) 확인을 받으시기 바랍니다. "100% 합법/안전"이라고 보장하지 않습니다.
| 항목 | 내용 |
|---|---|
| 라이선스 | Apache License, Version 2.0 (전문: LICENSE) |
| 저작권자 | SoDam AI Studio |
| 연도 | 2026 |
| 고지 | NOTICE 파일에 저작권·상표 고지 포함 |
| 외부 런타임 의존성 | 0개(Node.js 표준 기능만 사용, package.json 확인 가능) |
| 행위 | 가능 여부 |
|---|---|
| 수정 | ✅ |
| 복제 | ✅ |
| 재배포 | ✅ |
| 상업적 사용 | ✅ |
| 판매 | ✅ |
| 서비스로 운영(SaaS) | ✅ |
| 교육 목적 사용 | ✅ |
| 회사·고객사 납품 | ✅ |
위 전부 Apache-2.0의 조건인 LICENSE·NOTICE 사본 보존, 수정한 파일에 변경 사실 표시를 지키면 가능합니다.
이 플러그인 자체는 Apache-2.0으로 무료이지만, Anthropic Claude·OpenAI Codex의 모델 사용료·이용약관은 이 플러그인의 라이선스와 완전히 별개이며, 각 회사의 약관을 따로 따릅니다. 상업적으로 활용할 계획이라면 Claude(Anthropic)·Codex(OpenAI) 각각의 상업 이용 정책을 반드시 별도로 확인하세요. 연결하는 외부 MCP 서버·API의 약관도 마찬가지입니다.
"Claude", "Claude Code"는 Anthropic의 상표이며, "Codex"는 OpenAI의 상표입니다. 이 프로젝트는 위 상표를 오직 호환 대상을 설명하는 용도로만 사용하며, 로고를 무단으로 사용하지 않고, 공식 제휴·보증·후원 관계로 오인시키지 않습니다. 이 프로젝트는 Anthropic·OpenAI가 만들거나 공인한 공식 제품이 아닌, 비공식 서드파티 도구입니다. "SoDam", "소담"은 이 프로젝트(SoDam AI Studio)의 명칭입니다.
이 소프트웨어는 "있는 그대로(AS IS)" 제공되며 어떠한 명시적·묵시적 보증도 하지 않습니다(상품성·특정 목적 적합성·권리 비침해 보증 포함). 저작권자·기여자는 이 소프트웨어의 사용으로 발생하는 어떠한 직접·간접·특별·부수적 손해에도 법이 허용하는 최대 한도 내에서 책임지지 않습니다. "완벽하게 안전"·"100% 보장" 같은 표현은 쓰지 않습니다 — 사용 결과는 전적으로 사용자 책임이며, 이 문서는 참고용입니다.
타인의 저작물·상표·로고·개인정보·고객사 정보·비밀정보는 이 저장소에 포함되어 있지 않습니다. GPL/AGPL 등 강한 카피레프트 라이선스 코드는 의도적으로 차용하지 않았습니다(상업·납품 시 소스 공개 의무가 전파될 위험이 있기 때문) — gh CLI로 참고 저장소 4곳의 실제 라이선스를 직접 확인했으며(GPL/AGPL 0건), 그 출처 고지는 THIRD_PARTY_NOTICES.md에 별도 정리했습니다.
이 프로젝트의 코드·문서 중 상당 부분은 AI 코딩 도구의 도움을 받아 작성되었습니다. 안전장치(F4) 등 핵심 로직은 반복적인 실사용 테스트로 검증했지만, AI가 작성한 코드가 사람이 작성한 코드와 동일한 수준의 완전성·정확성을 자동으로 보증하는 것은 아닙니다 — 프로덕션·상업 환경에 적용하기 전 자체 코드 검토를 권장합니다.
Claude Code:
- 입력칸에
/plugin uninstall sodam-agentic(또는 마켓플레이스 화면에서 제거 선택). - 확인:
/sodam-agentic를 쳐도 명령이 더는 안 뜨면 제거 완료.
Codex:
- 설치가 "파일 복사" 방식이므로, 내 프로젝트의
.agents/skills/·.agents/hooks/·.agents/data/폴더를 직접 삭제하면 됩니다..codex/hooks.json에 등록된PreToolUse항목도 지우려면 해당 JSON 파일을 직접 편집해 그 부분만 삭제하면 됩니다.
남는 데이터(중요): 플러그인을 제거해도 안전 기록 파일(~/.sodamagentic/safety-log.jsonl)은 자동으로 지워지지 않습니다(플러그인 폴더 밖, 사용자 홈 폴더에 저장되기 때문입니다). 완전히 지우고 싶으면 이 파일을 직접 삭제하세요.
이 저장소는 공개(PUBLIC) 상태이지만, 여전히 개발자 본인의 개인용 도구로 운영 중이며 별도의 공식 기여(PR) 절차는 아직 마련돼 있지 않습니다. 문의·버그 제보는 GitHub 이슈로 남겨주시면 확인하겠습니다.
MCP(Model Context Protocol)는 AI가 외부 도구·서비스와 연결해 쓸 수 있게 해주는 방식입니다. 아래 4개는 소담 에이전틱이 자체 안전 기준(공식 저장소인가·소스코드가 공개돼 직접 확인했는가·잘 알려진 곳이 관리하는가·문제 이력은 없는가, 4개 중 2개 이상 충족)으로 검토해본 참고용 후보입니다.
⚠️ 정직 안내: 이 목록은 참고용 추천일 뿐입니다. 소담 에이전틱이 이 MCP들을 자동으로 설치하거나 켜주지 않습니다 — 필요하다고 판단되면 각자/plugin화면 등에서 직접 설치·연결해야 합니다.
| MCP | 용도 | 참고사항 |
|---|---|---|
| Context7 (Upstash) | 라이브러리·프레임워크 최신 문서를 AI가 바로 찾아보게 해줌 | — |
| Playwright MCP (Microsoft) | 웹페이지를 AI가 직접 열어보고 클릭·확인하게 해줌 | 웹페이지 내용에 숨겨진 이상한 지시가 있으면 AI가 속을 수 있는 위험은 이런 종류 도구 전반의 한계입니다 |
| Chrome DevTools MCP (Google) | 지금 실행 중인 웹앱을 AI가 직접 열어 화면·오류·성능을 확인하게 해줌 | 버전 1.1.0 이상을 쓰세요(2026-08-17 공개된 보안 문제가 그 이전 버전에 있었고, 1.1.0에서 고쳐졌습니다) |
| GitHub 공식 MCP Server (GitHub) | 저장소·이슈·PR을 AI가 직접 다루게 해줌 | 소담 계열에서는 아직 실사용 이력이 없어 참고 후보로만 표시합니다 |
근거·검토 과정은 .PRD/12_PHASE3_GATE3_MCP_CURATION.md에 자세히 남겨뒀습니다(개발자 참고용, 이 저장소엔 포함 안 됨).
문서 버전 기준일: 2026-09-01 (플러그인 버전 v0.2.8) · 이 문서는 "지금까지 실제로 구현·검증된 코드" 기준으로 작성되었습니다(직접 실행해 확인하지 않은 내용은 §8에 정직하게 표시했습니다).