meta-plan — AI 여럿이 합의할 때까지 PRD를 고쳐 쓰는 Claude Code 플러그인을 만들며 배운 것

먼저 양해 한 가지 — 이 글은 구조만 설명한다

meta-plan은 사내 지식베이스(회사 안에 정리해 둔 문서 모음)와 내부 도구 여러 개에 붙어서 돌도록 만들었다. 그 연결을 걷어 내면 그대로 쓸 수 있는 부분이 많지 않아서 코드를 공개하지 않는다. 그래서 이 글에는 설치법도 명령어도 없다. 대신 단계마다 왜 그 단계가 필요했는지를 적었다. 자기 팀에서 같은 구조를 흉내 낼 때 기준으로 쓰면 된다.

Claude Code(클로드 코드)는 터미널(명령어를 쳐서 컴퓨터를 다루는 창)에서 대화로 코드를 짜고 파일을 고치게 하는 앤트로픽의 AI 도구다. 플러그인은 거기에 기능을 덧붙이는 꾸러미다. 이런 도구를 코딩 에이전트라고 부른다. 에이전트는 사람 대신 여러 단계를 스스로 밟아 일을 끝내는 AI 실행 단위다. 글 끝에는 Claude Code 같은 코딩 에이전트에 붙여 넣으면 비슷한 플러그인을 만들어 주는 프롬프트를 두었다.

PRD가 무엇이고, meta-plan은 그걸 어떤 순서로 쓰나

PRD(Product Requirements Document, 제품 요구사항 문서)는 만들 기능이 무엇을 해야 하는지, 왜 필요한지, 무엇을 하면 완료인지를 적은 문서다. 개발자가 코드를 짜기 전에 읽는 설계도의 앞장이라고 보면 된다. 요즘은 이 문서를 AI에게 쓰게 하는 일이 많은데, 한 번 시키고 끝내면 그럴듯하지만 근거 없는 문장과 빠진 화면이 섞여 나온다.

meta-plan은 주제 한 줄을 받으면 사람에게 다시 묻지 않고 일곱 단계를 이어서 돈다. 먼저 브리프(목표·맥락·제약을 적은 한 장짜리 요약)와 리서치 요약을 만들고, Planner가 PRD 초안을 쓴다. 이어서 Architect가 가장 강한 반론을 내고 Critic이 통과 여부를 판정한다. Critic이 APPROVE하지 않으면 Planner가 고쳐 쓴 판으로 다시 돈다.

합의가 나면 PRD를 쓴 대화와 분리된 리뷰어가 문서를 처음부터 끝까지 통독하고, 화면이 있는 기획이면 화면마다 목업을 만든다. 목업은 실제로 동작하지는 않지만 화면 모양과 상태를 미리 그려 본 시안이다. 마지막으로 최종 리뷰와 수정을 하고, 검증 단계가 지적마다 실제로 고쳐졌는지 대조한다. Planner·Architect·Critic·리뷰어·검증자는 모두 따로 띄우는 에이전트이고, 지시문과 권한이 서로 다르다.

쓰는 AI와 따지는 AI를 나눈다 — Planner·Architect·Critic

이 합의 방식은 oh-my-claudecode(Claude Code에 여러 에이전트와 작업 방식을 얹어 주는 오픈소스 확장 묶음)의 ralplan에서 가져왔다. 세 역할 하나하나는 앞선 글에서 자세히 다뤘으니, 여기서는 왜 나눠야 하는지만 짧게 적는다. 같은 AI에게 '방금 쓴 걸 검토해 줘'라고 하면 대개 칭찬과 사소한 손질이 돌아온다. 쓴 맥락을 그대로 들고 있으니 자기가 세운 가정을 의심할 이유가 없다. 그래서 역할을 셋으로 나눴다. Planner는 브리프와 리서치를 근거로 초안을 쓰고, 리뷰를 받아 고친다. Architect는 그 판에서 가장 강한 반론과, 실제로 무엇을 얻으려면 무엇을 내줘야 하는지(트레이드오프)를 낸다. Critic은 품질 기준표로 APPROVE(통과)·ITERATE(고쳐서 다시)·REJECT(반려) 중 하나를 판정한다. Architect와 Critic은 읽기만 하고 문서를 고치지 않는다.

Architect와 Critic은 같은 판을 동시에, 서로의 결과를 보지 않고 읽는다. Critic이 Architect의 반론을 먼저 보면 그 반론에 끌려 같은 곳만 보게 된다. 둘의 결과가 다 나온 뒤에야 저장해서 Planner에게 넘긴다. 동시에 돌리니 기다리는 시간도 판마다 한 번으로 줄었다.

합의는 최대 5판까지만 돈다. 5판 안에 APPROVE가 안 나오면 억지로 통과시키지 않고, 더 강한 검토로 올리거나 그 쟁점을 사람이 정할 결정으로 남긴다. 판마다 그 시점의 문서를 통째로 저장한 사본(스냅샷)을 남겨 두어서, 무엇이 왜 바뀌었는지 나중에 따라갈 수 있다.

근거 없는 문장은 [미검증]으로 남긴다

PRD에서 가장 위험한 문장은 그럴듯한 사실 주장이다. '사용자 대부분이 모바일로 들어온다' 같은 문장은 틀려도 아무도 모른 채 설계의 전제가 된다. meta-plan은 사실 주장마다 근거를 붙이게 한다. 직접 잰 것은 [실측: 출처], 못 잰 것은 [미검증]과 함께 잴 방법을 적는다. 지금 제품이 어떻게 동작하는지는 지식베이스에서, 수치는 읽기 전용 조회로, 외부 사실은 원문 주소로 확인한다.

리서치 인용도 같은 규칙을 탄다. 웹 페이지를 요약해 주는 도구로 인용을 대조하면, 요약문 안에 비슷한 말이 있다는 이유로 통과하기 쉽다. 그래서 원문 텍스트를 직접 받아 인용이 글자 그대로 들어 있는지 스크립트(정해진 일을 자동으로 하는 작은 프로그램)로 확인한다. 링크가 주제와 맞는 것과 그 문장을 실제로 뒷받침하는 것도 따로 본다. 근거가 모자라면 결론을 쓰지 않고 '답할 근거가 부족하다'로 남긴다.

요구사항 문장은 한 문장에 한 가지 뜻만 담고, 수치나 조건으로 확인할 수 있게 쓴다. '빠르게'·'적절히' 같은 말은 검사 스크립트가 걸러 낸다. 목표마다 그 목표를 이루는 요구사항이 있는지, 요구사항마다 어느 목표에서 왔는지도 양쪽으로 맞춰 본다. 목표와 이어지지 않는 요구사항은 대개 누군가의 추측에서 나온 것이다.

법적 쟁점은 사람에게 묻기 전에 조문과 판례부터

개인정보·의료·광고·전자상거래가 걸리는 기획은 '이거 법적으로 괜찮나?'에서 일이 멈춘다. meta-plan은 이 질문을 바로 사람에게 넘기지 않는다. 국가법령정보센터 Open API로 법령 조문, 하위 법령, 법령해석례, 판례 원문을 찾아 쟁점마다 허용·조건부 허용·금지로 결론을 내고, 그 결론을 요구사항과 화면 문구, 동의 절차에 반영한다. API는 프로그램이 다른 서비스에 정해진 형식으로 데이터를 요청하는 창구다.

해석이 갈리면 법을 지키는 쪽으로 보수적으로 설계해서 결론을 낸다. 사람에게는 '이 기능을 빼면 법적 위험이 사라지지만 사업 목표 하나를 포기한다'처럼 법적 위험과 사업 목표를 맞바꾸는 결정만 올린다. 자동 검토이지 법률 자문은 아니라서 결론마다 확신도를 붙이고, 확신이 낮으면 자문을 권한다고 적는다.

만들면서 하나 배운 것이 있다. 판례와 해석례는 기본 설정인 제목 검색으로는 거의 걸리지 않는다. 판례 이름은 '손해배상(기)' 같은 사건명이라 쟁점어가 잘 들어 있지 않다. 검색 범위를 본문으로 바꾸는 값(search=2)을 줘야 걸린다. 같은 검색어로 제목 검색은 0건, 본문 검색은 3건이 나왔다.

쓴 문맥과 떨어진 리뷰어가 처음부터 끝까지 읽는다

합의 루프는 판 단위로 고친다. 그러다 보면 절마다 좋아졌는데 문서 전체로는 앞뒤가 안 맞는 일이 생긴다. 앞에서 정한 목표를 뒤의 요구사항이 따르지 않거나, 같은 용어를 두 뜻으로 쓰는 식이다. 그래서 합의가 끝나면 PRD를 쓴 대화와 분리된 리뷰어가 문서를 통째로 읽고 정해진 10개 항목으로 판정한다. 리뷰어는 문서를 읽고 판정하는 역할만 맡은 에이전트다.

리뷰어는 먼저 앞선 리뷰를 보지 않고 혼자 읽는다. 앞 리뷰를 먼저 보면 거기에 동조해서 같은 지적만 반복한다. 혼자 읽은 판정을 낸 다음에야 앞선 리뷰와 대조한다.

여기서 하나 더 배웠다. 리뷰어를 여럿 세워 다수결을 내면 안전해 보이지만, 만든 회사가 다른 모델끼리도 같은 곳에서 함께 틀리는 일이 많다. 그래서 같은 질문을 여러 번 묻지 않고 역할을 나눈다. 한 리뷰어는 원문과 대조하고, 한 리뷰어는 반례를 찾고, 한 리뷰어는 과장을 찾는다. 표 수보다 근거를 먼저 본다.

화면이 있으면 목업까지 만들어 본다

글로만 된 PRD는 화면에서 어긋난다. '목록에서 항목을 고르면 상세가 열린다'는 문장은 맞아도, 막상 그려 보면 목록이 비었을 때 무엇을 보여 줄지, 좁은 폰 화면에서 버튼이 어디로 가는지가 정해져 있지 않다. 그래서 기획에 화면이 있으면 화면마다 목업을 만든다.

목업은 화면마다 빈 상태·오류·불러오는 중 같은 상태와 폰·데스크톱 크기를 바꿔 볼 수 있게 만든다. PRD도 목차·검색·요구사항 필터가 붙은 웹 문서(HTML) 한 장으로 옮겨 그것을 정본으로 삼는다. 목업을 만든 뒤에는 스크린샷 묶음을 리뷰어가 따로 보고, PRD의 화면 표와 실제 목업 목록이 서로 맞는지는 검사 스크립트가 확인한다.

고친 쪽이 아니라 다른 쪽이 '고쳐졌다'를 확인한다

마지막 단계는 셋으로 나눴다. 최종 리뷰어는 PRD와 목업 전체를 읽고 지적 목록만 낸다. 고치지 않는다. 수정자는 그 목록을 받아 문서와 목업을 고치고, 지적마다 무엇을 했는지 남긴다. 검증자는 지적 하나하나를 고친 결과와 대조해서 정말 고쳐졌는지 판정한다. 검증자도 고치지 않는다.

나눈 이유는 단순하다. 고친 쪽이 '다 고쳤다'고 보고하면 대개 믿게 되는데, 실제로 열어 보면 일부만 고쳐져 있거나 다른 곳이 새로 깨져 있다. 이 플러그인 자체를 두 리뷰어에게 검토받았을 때도 그랬다. 지적 32건과 41건을 반영한 뒤 다시 대조하니 실제로 닫힌 것은 27건과 34건이었다. 검증에서 심각한 지적이 열려 있으면 수정과 검증을 한 번 더 돈다. 두 번 돌고도 남은 것은 숨기지 않고 보고에 싣는다.

사람에게는 끝에서 한 번만 묻는다

이런 파이프라인을 처음 만들면 단계마다 '이렇게 할까요?'를 묻게 된다. 그러면 사람이 자리를 비운 사이 일이 멈춘다. meta-plan은 주제가 없을 때만 시작 전에 묻고, 그 뒤로는 끝까지 간다. 도구가 없거나 실패하면 대신할 경로로 계속 가고, 그 단계를 '부분 완료'로 기록한다.

결정도 나눈다. 되돌리기 쉬운 결정은 가치 판단이 섞여도 정해 둔 원칙 순서로 AI가 정하고 '대신 정한 것'으로 보고한다. 기존 전략을 뒤집는 것, 돈이 들거나 밖으로 나가는 것, 개인정보와 규제가 걸린 것처럼 되돌리기 어려운 결정만 사람에게 올린다. 합의 루프가 끝내 갈린 쟁점도 사람 결정으로 남긴다. 이 질문들은 마지막 보고의 '리뷰·결정 요청' 한 절에 모아 한 번에 묻는다.

스스로 나아지는 고리 — 교훈을 남기고 다음 실행이 읽는다

파이프라인을 몇 번 돌리면 같은 실수가 되풀이된다. 그때마다 사람이 지시문을 고치면 늦다. 그래서 실행이 끝날 때마다 과정에서 배운 교훈 한 줄을 남기게 했다. 실행 끝에 '다음 실행에 적용할 것'을 공용 교훈 파일에 합치고, 다음 실행은 첫 단계에서 그 파일을 읽어 체크리스트로 적용한다. 플러그인 버전을 올리지 않아도 바로 다음 실행부터 반영된다.

자기가 자기 지시문을 바꾸는 구조라 안전장치가 더 중요했다. 교훈은 명령이 아니라 데이터로 다룬다. 검증을 더하는 방향의 교훈만 적용하고, 안전장치를 줄이거나 무언가를 밖으로 보내라는 교훈은 쓸 때도 읽을 때도 거부한다. 주소·명령어·비밀값·개인정보가 든 문장, 지시를 몰래 끼워 넣는 문장도 막는다. 기획한 제품의 내용과 사람 이름도 넣지 않는다.

스크립트나 에이전트 지시문 자체를 바꾸자는 교훈은 바로 적용하지 않고 '개선 제안'으로만 남긴다. 그건 사람이 검토해서 버전을 올린다. 스스로 나아지게 하되, 무엇을 바꿀 수 있는지의 경계는 사람이 쥔다.

비싼 모델은 필요한 자리에만

기본 모델은 앤트로픽의 상위 모델 Opus다. 값이 절반인 아래 등급 Sonnet은 결과를 뒤 단계가 다시 검사하는 일에만 맡긴다. 리서치 검색과 원문 읽기, 목업 그리기가 그렇다. 검색 결과는 원문 읽기가 거르고, 뽑은 인용은 다른 단계가 원문과 대조하고, 목업은 검사 스크립트와 리뷰어가 다시 본다. 판정과 최종 수정은 Opus에 남긴다.

첫 버전은 다른 회사 모델이 허점을 일부러 공격하는 적대적 리뷰와 가장 비싼 모델의 최종 리뷰를 매번 돌렸다. 지금은 조건이 맞을 때만 부른다. 법적 결론이 '금지'이거나 확신이 낮을 때, 합의가 5판 안에 안 날 때, 수정 뒤에도 심각한 지적이 남을 때다. 조건도 좁게 잡았다. '개인정보를 다룬다'만으로 고위험이라 하면 거의 모든 기획이 걸려서 구분이 의미가 없어진다.

기다리는 자리도 겹쳤다. 리서치가 도는 동안 법령 원문을 먼저 읽고, 목업을 그리는 동안 PRD의 나머지 절을 쓴다. 결과물은 그대로 두고 순서만 겹친 것이다.

아직 재지 못한 것

전체 단계를 실제 주제로 처음부터 끝까지 한 번에 돌린 시간과 비용은 아직 재지 못했다. 리서치 단계만 따로 돌린 시험은 에이전트 7개로 3분에서 12분 사이가 걸렸다. 플러그인을 만들기 전에 같은 순서를 손으로 돌린 기획 하나는 요청부터 최종 보고까지 약 4시간 30분이 걸렸고, 그 안에 합의 5판과 60건이 넘는 리뷰 지적 반영이 들어 있었다.

직접 만들어 보기 — 붙여 넣는 프롬프트

아래 프롬프트를 Claude Code나 비슷한 코딩 에이전트에 그대로 붙여 넣으면, 사내 연동 없이 웹 검색과 로컬 파일만으로 같은 구조의 플러그인을 만들어 준다. 두 번째 모델 CLI(명령어로 부르는 다른 회사 AI 도구)가 있으면 분리 리뷰에 쓰고, 없으면 같은 모델을 새 대화로 띄워 대신한다.

만들어지면 첫 실행은 작은 주제로 해 보고, 끝난 뒤 쌓인 교훈 파일을 직접 열어 읽어 보는 게 좋다. 이상한 교훈이 들어갔다면 그 자리에서 지우면 된다.

Claude Code 플러그인 "plan-loop"를 만들어 줘. 주제 한 줄을 받아 리서치부터 검증된 PRD까지 만드는 기획 파이프라인이다.
사내 시스템 연동은 쓰지 않는다. 도구는 웹 검색, 로컬 파일, (있으면) 두 번째 모델 CLI만 쓴다.

[산출물] docs/prd/<slug>/ 아래
- 00-brief.md: 목표·맥락·제약·완료 기준·하위 질문
- research.md: 출처 URL과 원문 인용이 붙은 요약
- prd.md: 정본. 사실 주장마다 [실측: 출처] 또는 [미검증: 잴 방법]
- legal.md: 법적 쟁점별 결론·근거 조문·판례
- reviews/: 판별 스냅샷, 리뷰·판정 기록
- mockups/: 화면별 HTML 목업(화면이 있을 때만)
- report.md: 상태(완료/부분 완료/미완료)와 사람에게 묻는 결정
- 플러그인 폴더의 lessons.md: 실행마다 쌓이는 교훈

[에이전트 — 한 줄 책임]
- planner: 브리프·리서치로 PRD를 쓰고 리뷰를 반영해 고친다
- architect: 읽기 전용. 그 판의 가장 강한 반론과 트레이드오프를 낸다
- critic: 읽기 전용. 품질 기준으로 APPROVE/ITERATE/REJECT를 판정한다
- reviewer: PRD를 쓴 문맥과 분리돼 문서 전체를 통독하고 체크리스트로 판정한다
- legal: 법령·판례 원문으로 쟁점별 결론을 낸다
- fixer: 최종 리뷰 지적을 고치고 지적별 처리 결과를 남긴다
- verifier: 읽기 전용. 지적마다 실제로 고쳐졌는지 대조한다

[단계]
0. lessons.md를 읽고 이번 주제에 맞는 항목을 체크리스트로 쓴다.
1. 브리프를 쓰고 웹 검색으로 리서치한다. 인용은 원문에 글자 그대로 있는 것만 쓴다.
2. planner 초안 → architect와 critic을 동시에, 서로 결과를 못 보게 돌린다
   → APPROVE까지 반복, 최대 5판. 안 되면 그 쟁점을 report.md의 결정으로 남긴다.
3. 법률 검토: 개인정보·의료·광고·전자상거래 등 쟁점이 있으면 국가법령정보센터 Open API
   (https://www.law.go.kr/DRF/lawSearch.do, OC는 환경변수 LAW_API_OC)로
   target=law(법령)·prec(판례)·expc(법령해석례)를 찾고 lawService.do로 원문을 읽는다.
   판례·해석례는 search=2(본문 검색)로 찾아야 걸린다. 쟁점마다 허용/조건부 허용/금지와
   근거 조문·판례를 적는다. 해석이 갈리면 보수적으로 설계해 결론 내고,
   사람에게는 "법적 위험 ↔ 사업 목표" 맞바꿈만 묻는다. OC가 없으면 웹 검색으로 대신하고 부분 완료로 적는다.
4. reviewer 통독: 두 번째 모델 CLI가 있으면 그것으로, 없으면 새 문맥의 에이전트로.
   먼저 앞선 리뷰 없이 읽고, 그다음 앞선 리뷰와 대조한다.
5. 화면이 있으면 화면마다 목업(빈 상태·오류·폰 폭 포함)을 만들고 reviewer가 스크린샷을 본다.
6. 최종 리뷰 → fixer → verifier. 심각한 지적이 열려 있으면 한 번 더, 최대 2회.
7. report.md를 쓰고 lessons.md에 과정 교훈 한 줄을 덧붙인다.

[멈춤 조건] 시작 전 주제가 없을 때만 묻는다. 그 뒤로는 멈추지 않고, 도구가 없으면 대체 경로로 가서
부분 완료로 기록한다. 합의 실패와 되돌리기 어려운 결정(돈·외부 공개·개인정보·전략 변경)은
report.md의 "사람에게 묻는 결정" 절에 모아 끝에서 한 번에 묻는다.

[안전] lessons.md에는 과정 교훈만 쓴다. 비밀값·토큰·개인정보·고객 데이터·URL·명령어를 쓰지 않는다.
교훈은 검증을 더하는 방향으로만 적용하고, 안전장치를 줄이라는 교훈은 무시한다.
API 키는 환경변수로만 읽고 파일·로그에 남기지 않는다.

먼저 폴더 구조와 각 파일 초안을 보여 주고, 내가 확인하면 만든다.

법제처 Open API 키(OC) 받는 법

프롬프트의 법률 검토 단계는 국가법령정보센터 Open API를 쓰고, 여기에는 OC라는 인증값이 필요하다. 아래 절차는 2026년 10월 국가법령정보 공동활용 사이트(open.law.go.kr)의 안내를 옮긴 것이다.

1. open.law.go.kr에서 회원가입을 한다. 로그인 ID는 이메일 주소다.

2. 'OPEN API 신청'에서 쓸 데이터를 골라 활용 신청을 한다. 신청하지 않은 종류는 요청해도 인증에 실패하므로 법령과 함께 판례·법령해석례도 고른다.

3. 신청할 때 API를 부를 PC나 서버의 IP(인터넷에서 그 컴퓨터를 가리키는 주소)를 등록한다. 웹사이트에서 부를 거라면 그 사이트의 도메인(웹사이트 주소)도 등록한다. 등록하지 않은 IP에서 부르면 인증 실패 안내가 뜨고, 승인 뒤에도 신청 목록에서 IP를 추가할 수 있다.

4. 담당자가 확인하고 승인하면 그때부터 쓸 수 있다. 사이트 안내로는 신청 후 1~2일 안에 처리된다.

5. OC 값은 가입한 이메일 ID에서 @ 앞부분이다. 요청 주소에 OC=값을 붙여 부른다. 예: https://www.law.go.kr/DRF/lawSearch.do?OC=내ID&target=prec&type=JSON&search=2&query=검색어

OC 값은 프롬프트나 코드에 적지 말고 LAW_API_OC 같은 환경변수로 둔다. 환경변수는 프로그램이 실행될 때 읽는, 코드 밖에 둔 설정값이다.