마사카타 마사요시(上原正吉) (EarthLink Network Co., Ltd.)입니다. Claude Code를 개발의 주체로 삼아 20개가 넘는 제품을 혼자 동시에 개발하고 운영하고 있습니다. 이것이 현장에서 측정된 기록입니다.

규율은 문서가 아닌 스킬로 배포한다 — ELN workflow의 165개 스킬 소개

規律は文書ではなくスキルで配る — ELN workflow の165スキルを紹介します

결론

• 무엇을 만들었는가: 개발의 규율, 품질 기준, 사양 프로세스를 Claude Code의 스킬(AI가 따라야 하는 절차서와 강제 게이트 세트)로 구현하여 모든 프로젝트에 배포하는 자사 플러그인 그룹입니다.
  ELN workflow
  스킬은 2026년 9월 기준으로 165개가 있습니다. - 왜 만들었는가: 개발 표준은 문서에만 적어 놓는다고 해서 지켜지지 않기 때문입니다. 지켜지는 것은 절차에 통합되었을 때뿐입니다. 사람이 잊어도, AI가 잊어도 게이트가 다음으로 진행되지 않으면 규율은 실행됩니다.
• 핵심 요점: AI에게 개발을 맡길수록 'AI가 올바르게 했는지'를 사람이 매번 확인하는 작업이 병목 현상이 됩니다. 그 확인 자체를 기계화하여 배포하는 것이 이 플러그인의 역할입니다.

본문 (독해 시간 약 7분)

이 연재에서 소개했던 인증, 알림, 결제는 모두 '모든 제품에 반드시 필요한 기능'을 기반으로 모은 이야기였습니다. 이번에는 성격이 다릅니다. 모은 것은 기능이 아니라, 개발하는 방식 그 자체입니다.

claude-plugins の製品ページ。仕様プロセスと品質基準を全社へ配る社内プラグイン基盤（https://www.eln.ne.jp/products/claude-plugin の実画面）

개요만으로는 전달되지 않기 때문에, 실제로 존재하는 스킬 몇 가지를 소개하겠습니다. 이름과 역할은 실제와 같습니다.

AI의 보고를 신뢰하지 않는ための 스킬

• eln-verify-before-claim

— '완료했습니다'라고 말하기 직전에, 주장과 증거(실측 로그/테스트 출력)를 기계적으로 대조합니다. 증거가 없으면 보고할 수 없습니다.

• eln-report-guard

— '빌드가 통과했다', 'unit 테스트가 통과했다'와 같은 약한 대리 증거만으로는 완료 보고를 막고, 실제 관측으로 격상시킵니다.

• answer-the-question-first

— '끝났어?'라는 질문에 대해 경위 설명부터 시작하지 않고 첫 문장에서 바로 답변하게 합니다.

• eln-execute-dont-defer

— AI가 '이건 사람이 수동으로 해 주세요'라며 사람에게 떠넘기는 것을 막습니다. 스스로 실행할 수 있는 작업은 실행하도록 만듭니다.

• no-tracked-leftovers-at-goal

— 잔여 태스크가 남아있는데도 '완료'라고 선언하는 것을 막습니다. 완료의 신호는 잔여 태스크 제로입니다.

조사 및 디버깅의 규율

• evidence-based-debugging

— 버그 조사에서 추측만으로 코드를 고치는 것을 금지하고, 먼저 로그/DB/실제 요청 관측을 요구합니다.

• zero-result-query-check

— 검색이나 쿼리가 0건일 때 '존재하지 않는다'고 단정 짓지 못하게 합니다. 검색 조건 자체의 타당성을 먼저 검증합니다.

• classify-failure-before-rerun

— CI가 실패했을 때, 원인을 분류한 후에 재실행합니다. '일단 한 번 더'라는 맹목적인 리트라이를 방지합니다.

• read-current-state-before-implementing

— 구현에 들어가기 전에 대상의 현황을 일차 정보로 읽게 합니다. 이미 존재하는 기능의 중복 구현을 막습니다.

돈과 운영 환경(Production)을 지키는 스킬

• eln-cost-watch

— 과금에 영향을 주는 변경 전에 월별 예상 비용을 요구하고, 변경 후에는 실측이 수렴할 때까지 '비용이 줄었다'고 말하지 못하게 합니다.

• dynamodb-best-practices

— 데이터베이스 설계 단계에서 월별 비용을 숫자로 산출하게 합니다. 시뮬레이션(試算) 없는 착수는 반송됩니다.

• billing-safety

— 결제/과금 코드에 접근할 때의 전용 규율입니다. 이중 과금이나 오청구로 이어지는 변경을 막습니다.

• verify-after-deploy

— 배포하고 끝내는 것을 금지합니다. 운영 환경에서의 실제 검증까지가 배포입니다.

• eln-deploy-target-checklist

— 변경이 반영되어야 할 배포 대상을 모두 나열하게 하고, 일부만 반영된 상태에서 '완료'라고 말하지 못하게 합니다.

팀으로서 일하기 위한 스킬

• eln-adversarial-review

— main에 병합(merge)하기 전에 여러 관점에서 반증을 시도하는 적대적 리뷰를 필수화합니다. 기록이 없는 merge는 기계적으로 거부됩니다.

• eln-codex-cross-check

— 다른 AI (Codex)에게 읽기 전용으로 크로스 리뷰하게 하여, 하나의 AI의 착각을 다른 AI가 지적하도록 합니다.

• eln-acceptance-ledger

— 대화 도중에 늘어난 '이것도 해줘'를 장부에 기록하고, 증거 없이 체크하지 못하게 합니다.

• progress-record/progress-recall

— 조사나 시행착오의 중간 경과를 git 관리 기록에 남기고, 세션이 바뀌어도 이어서 재개할 수 있게 합니다.

• prioritize-users-restated-goal-over-current-thread

— 사람이 목표를 다시 말하면, 진행 중인 작업보다 목표 재설정을 우선하여 재계획하게 합니다.

하나씩의 내용과 실제로 사고를 막은 장면은 이 시리즈 기사로 순차적으로 작성해 나가겠습니다.

게이트의 현물 — '잘못된 완료 보고'에 이름을 붙이다

완료 게이트의 내용을 한 단계 더 구체적으로 적습니다. AI의 수상한 보고는 패턴에 이름을 붙이면 기계로 감지할 수 있게 됩니다. 실제로 정의하고 있는 검지 클래스 중 일부입니다.

• FALSE_SUCCESS

— 증거 없는 '완료했습니다'

• WEAK_PROXY

— 빌드나 단위 테스트 통과만을 근거로 '운영 환경에서 작동한다'고 말하는 것

• MOCK_THEATER

— 전부 목(mock) 테스트가 통과한 것을 '작동한다'는 증거로 사용하는 것

• NARROW_PROBE

— 1개의 파일만 보고 '그 기능은 존재하지 않는다'고 단정하는 경우
FALSE_DEFERRAL

— 직접 실행할 수 있는 커맨드 작업을 '수동으로 해달라'며 사람에게 넘기는 경우
RESIDUAL_COMPLETION

— 남은 태스크를 나열하며 '완료입니다'라고 마무리하는 것

증거에도 강함의 서열을 정의했습니다. 정적 검사 < 단위 테스트 < 통합 테스트 < 실기(실제 기기) 통과 검증 < 실제 관측(운영 환경).
외부와의 경계(결제, Webhook, 배포)와 관련된 주장은 실기 이상의 증거가 없으면 통과시키지 않습니다.

대화의 마지막에도 문지기가 있습니다. 응답이 '완료'를 선언하며 끝나려 할 순간, 글이 아닌 git의 실제 상태와 대조합니다. main에 포함되지 않은 변경 사항은 없는지. 열어둔 PR(Pull Request)은 없는지. 커밋하지 않은 변경 사항은 남아있지 않은지. 단 하나라도 남아있으면 선언은 되돌려지고, 미완료 항목이 구체적인 이름으로 나열됩니다.

똑똑한 게이트는 만들지 않는다 — 측정으로 정한 설계 원칙

여기까지 읽으면 '게이트를 더 똑똑하게 하면 좋겠다'고 생각할 수 있지만, 반대의 교훈도 있습니다.

한때 완료 게이트에 '증거가 진짜인지 아닌지'를 패턴 매칭으로 판별시키는 안을 검토했습니다. 실제 기록 191행에 대입하여 측정해 본 결과, 진짜 증거의 76%를 잘못해서 가짜로 걸러냈습니다.
이 측정을 근거로 방침을 고정했습니다. 기계가 게이트에서 할 수 있는 것은 구조 검사(기록이 있는지/남은 건이 0인지/서식을 충족하는지)뿐입니다. 내용 자체가 진짜라는 의미의 판단은 독립적인 리뷰어(다른 AI 또는 사람)에게 분리합니다. 게이트를 똑똑하게 만들고 싶은 유혹은 측정으로 기각되었습니다.

새로운 게이트 도입 절차도 정했습니다. 갑자기 작업을 멈추는 것이 아니라, 먼저 '관측 모드'로 경고 기록만 쌓아두고, 오탐지율을 실측한 후에 멈추는 쪽으로 승격시킵니다. 한 가드는 최근 30일/400세션의 실행 이력을 분석하여 '중단해야 할 작업은 월 9건 정도이며, 거의 전부가 진짜'임을 확인한 후에 차단을 활성화했습니다. 아무리 그럴듯해 보이는 규칙이라도 오발률을 측정하기 전까지는 사람을 막지 않습니다. 게이트를 늘리는 쪽의 책임이라고 생각합니다.

또 다른 원칙은 게이트가 절대로 사람을 가두지 않는다는 것입니다. 검사 툴이 고장 났다면 그냥 통과시키고(멈추는 것이 아니라), 차단 해제 수단은 사용자 본인의 명시적인 조작으로만 한정하며, AI가 스스로 해제할 수 있는 뒷문은 의도적으로 만들지 않았습니다.

게이트가 생기는 순간 — 실패 3연발의 기록

많은 스킬에는 탄생 계기가 된 실제 실패가 있습니다. 세 가지를 들겠습니다.

검색 0건 오진(4월). 데이터베이스 로그를 timestamp라는 항목명으로 검색해서 0건이 나오고, '로그 기반 시설이 고장났다'고 오진했습니다. 올바른 항목명은 createdAt이었고, 실제로는 7,406건의 로그가 있었습니다. 그 이후로 0건일 때는 항목명・타입・기간을 검증하고, 필터 없이 검색해서 '데이터 자체는 있다'는 것을 확인한 후에야 '존재하지 않는다'고 말할 수 있는 스킬이 작동하게 되었습니다.

1일 43달러 청구(9월 3일). 늘어나는 테이블에 대한 주기적 읽기를 시뮬레이션 없이 추가한 결과입니다. 하루당 읽기량 3억 유닛. 사후에 공식에 대입해 보니, 청구액과 거의 일치했습니다. 사전에 이 한 줄을 제시했더라면 막을 수 있었을 겁니다. 그래서 지금은 데이터베이스를 건드리는 설계를 하기 전에 '읽기량 × 단가'의 공식으로 월별 금액을 숫자로 만들지 않으면 다음 단계로 나아갈 수 없습니다.

문서는 통과했다(9월 6일). 아이러니하게도, 비용 규율을 스킬의 문면으로 정전화한 3일 후에, 과금에 영향을 주는 설정 변경이 시뮬레이션 제로인 상태로 실행되었습니다. 문서든 스킬의 문명이든, 실행하는 순간 읽히지 않으면 소용없습니다. 이 실패로 인해, 비용 관련 규율은 '커맨드가 실행되는 순간 가로막는' 게이트로 승격했습니다. 지금은 과금 구성을 변경하는 커맨드는 시뮬레이션 장부(台帳)가 없으면 실행 자체가 거부됩니다.

실패할 때마다, 같은 실패를 기계적으로 불가능하게 만듭니다. 스킬이 165개나 있는 것은, 그만큼 실패해 온 기록이기도 합니다. 실패를 사람의 반성으로 끝낼 것인가, 기계의 게이트로 바꿀 것인가. 이 차이가 반년 후의 사고율을 가릅니다.

카탈로그 자체도, 시스템으로 지킨다

165개까지 늘어나니, 만든 본인조차 모든 용도와 호출 방법을 기억할 수 없습니다. 실제로 7월 2일에는 90개였던 스킬이, 7월 20일에는 121개, 8월에 154개, 지금은 165개입니다. 늘어나는 목록을 손글씨로 관리하면, 반드시 실체와 어긋납니다.

그래서 스킬 목록표도 자동 생성했습니다. 각 스킬의 등록 정보에는 분류, 목적, 사용 시기, 호출 방법 4가지 항목이 필수이며, 이 정보만으로 카탈로그가 기계적으로 생성됩니다. 카탈로그는 16개 카테고리로 나뉘어 있으며, 호출 방법은 3가지 유형으로 정리되어 있습니다. 상황에 반응하여 자동으로 로드되는 것이 69개, 이름으로 명시적으로 호출하는 것이 68개, 임의의 타이밍에 사용하는 것이 28개입니다. 사용 측에서는 '헷갈릴 때는 명시적 호출 68개만 기억하면 된다'는 안내를 하고 있습니다.

구조적인 면에서도 이중화되어 있어, 필수 항목이 없으면 생성이 멈추고, 저장된 카탈로그가 오래되면 CI(지속적 통합)가 멈춥니다. 손으로 작성한 목록이 은근히 남아있어 실체와 네 개의 숫자가 불일치했던 실패 경험도 있으며, 그 전말은 다른 글에 쓰았습니다.

규모감 — 4개월 반 만에 출시 289회

이 플러그인 자체의 개발 역시 이 플러그인의 규율 하에서 진행하고 있습니다(스스로 매일 사용하는 것이 품질의 원천입니다). 첫 커밋은 2026년 4월 28일. 거기서부터 4개월 반 만에 커밋 547건, 버전은 289회 개정되었습니다. 설계 결정 기록(ADR)은 139개. 스킬의 절차서는 총 26,000줄을 넘습니다.

또 하나의 계층으로, 세션에서 얻은 행동 교훈을 짧은 한 줄로 압축한 '본능'을 134건 축적하고 있으며, 매 세션 시작 시 신뢰도 높은 순서대로 자동 주입합니다. 스킬이 '지켜야 할 절차'라면, 본능은 '과거에 실패했던 상황의 감각적인 지점'입니다. 규칙은 배포할 뿐만 아니라 경험도 배포하는 것입니다. AI와의 개발 체제에서는 이 두 계층이 있어야 비로소 프로젝트를 넘나드는 학습이 돌아갑니다.

독자의 팀에서 어떻게 활용될까

이 플러그인 자체는 사내용이지만, 생각은 전용할 수 있습니다.

• 팀의 '지켜지지 않는 규칙'을 하나 골라 문서에서 절차 속 게이트로 옮겨보세요. 커밋 전 훅(pre-commit hook), CI 필수 체크, 템플릿 필수 항목 등입니다. 위치는 어디든 상관없으며, '지키지 않으면 진행할 수 없다'는 형태가 되는지가 분수령입니다. - AI에게 개발을 맡기고 있다면, AI의 완료 보고에 증거(실측 로그/테스트 출력)를 요구하는 게이트부터 시작하는 것이 효과적이었습니다. 저희의 165개도 처음에는 거기서 늘어났습니다.

전용 가능한 교훈

• 개발 표준은 문서만으로는 지켜지지 않습니다. 절차에 통합되어, 지키지 않으면 진행할 수 없는 형태가 되었을 때만 지켜집니다.
• AI와의 개발에서는 'AI의 진술을 검증하는 게이트'가 품질의 중심이 됩니다. 완료 보고, 디버깅, 리뷰, 비용 4곳부터 시작하면 효과적입니다.
• 규칙이 늘어난다면, 규칙 목록도 자동 생성하게 하세요. 손으로 작성한 목록은 반드시 실체와 어긋납니다.
• 규율의 위치를 한 곳(플러그인)에 모으면, 새로운 프로젝트의 시작일부터 동일한 품질 기준이 적용됩니다.

이 ELN workflow(AI 개발의 품질을 시스템으로 지키는 사내 플러그인)에 대한 글은, 생각하는 방식, 스킬의 내용물, 실제로 막았던 사고를 순차적인 시리즈로 공개해 나갈 예정입니다.

관심 있으신 분들은 '좋아요'와 기사 구독 부탁드립니다.

자사 제품 목록은 https://www.eln.ne.jp/products 에 모아두었습니다.

필자 소개

카미하라 마사요시(上原正吉). EarthLink Network Co., Ltd에서 AI 개발을 하고 있습니다. 2025년부터 Claude Code를 개발의 주체로 삼고, 현재 20개가 넘는 제품을 혼자 동시에 개발 및 운영하고 있습니다. 이 연재에서는 현장에서 실제로 일어난 일(잘된 것도, 실패도)을 숫자를 함께 쓰겠습니다.

또한, AI로 업무나 개발을 재편하고 싶은 회사/팀을 대상으로 AI 활용 컨설팅도 받고 있습니다. 상담은 www.eln.ne.jp에서 부탁드립니다.

EarthLink Network는 회사의 모든 업무를 AI로 돌리기 위해 필요한 것을 자체 제작하고 있습니다. 현재 만들고 있는 제품 목록과 개요는 이쪽에 모아두었습니다.

회사와 각 제품의 상세 내용은 공식 웹사이트 www.eln.ne.jp 를 참고해 주십시오.

Discussion