prompt-company — AI 직원 조직 (Claude Code Agent Teams)

AI 직원들로 이루어진 가상 조직. 직원(에이전트)들이 하나의 공유지식메모리를 함께 보고, 지식 수정은 **추적된 관련자들의 회의(거버넌스)**를 거쳐 이뤄진다. Claude Code의 Agent Teams 위에서 동작하도록 설계됐다.

이 레포는 "조직 하네스"다 — 행동(헌법·역할) + 결정적 코드(kb·minutes·decisions·friction·훅)를 담은 재사용 키트. 한 번 전역 설치한 뒤, 다른 프로젝트마다 company init 으로 켜서 실제 일· 회의·지식을 그 프로젝트에 쌓는다. 하네스는 공통, memory(지식·회의록·결정·마찰)는 프로젝트별.

세 덩어리

| 덩어리 | 위치 | 성격 | |--------|------|------| | 행동(프롬프트) | CLAUDE.md(헌법 인덱스), constitution/*(조항), operations/*(운영), ORCHESTRATOR.md(리더), .claude/agents/*.md(역할) | LLM | | 상태(데이터) | memory/knowledge proposals meetings decisions friction personal tasks | 파일 + git | | 조율(코드) | orchestration/kb.py · minutes.py · decisions.py · friction.py(결정적 CLI) · dashboard.py(관측 대시보드), .claude/hooks/*(observe 등) | 결정적 코드 |

거버넌스의 핵심(버전관리·stakeholder 추적·영향도 등급계산·투표집계·정족수 판정)은 프롬프트가 아니라 결정적 CLI가 수행한다 — "가짜 합의"와 집계 오류를 막기 위함. 네 CLI 모두 원자적 쓰기+파일 잠금(flock)으로 병렬 호출에도 안전하다.

무엇을 하나 (핵심 메커니즘)

• 공유지식 거버넌스 — 지식은 한 곳(memory/knowledge)에 모으고, 읽어 쓰면 stakeholder로 추적(read --agent, 어디 썼는지 --usage). 수정은 제안→양측 변론→근거 투표→집계→커밋. 등급(영향도 floor)에 따라 자동 커밋~전체 회의로 거버넌스가 비례한다. (헌법 3·4·5조 / kb.py)
• 역할 분업 — clarifier가 진짜 질문을 벼려 브리프(맥락 포함)를 만들고, 요청자 전용 researcher(메모리 무접근, 결과는 reports/ 리포트 파일)가 조사를 대행한다. engineer· designer가 내린 중요 결정은 reviewer가 과거 결정과 대조해 모순/비효율을 검출한다. steward(규약), facilitator(중립 회의), counsel(프로젝트 정합성 자문)이 받친다.
• 회의 정합성 — 모든 회의는 facilitator가 중재하고 회의별 counsel이 영향을 자문한다. 같은 모델끼리의 "가짜 합의"를 막으려 관점 다양성(blind-first·다른 입장 배정·렌즈)을 등급에 비례해 설계하고(operations/meeting-diversity.md), 교착·무응답에도 멈추지 않도록 타임박스· tiebreaker로 안전하게 종결한다(부재·교착=현상유지). 지식이 바뀌면 stakeholder는 진행 중 작업을 재검증한다. (헌법 11·12조)
• 결정 로그 — 구현·설계 결정과 트레이드오프 근거를 memory/decisions에 가볍게 기록(공유 지식과 별개). reviewer가 검토하고, 구속력 있는 것만 지식으로 승격. (decisions.py)
• 진화 루프 — 운영 중 비효율을 마찰 신호로 잡고(friction.py) **회고(retro)**가 반복되는 체계 비효율을 골라 고친다. 지식뿐 아니라 프레임(헌법·역할·파라미터)도 같은 엄격함으로 개정 하고, 변경엔 가설·재검토를 달아 안 먹히면 롤백한다(규칙 비대 방지). (헌법 13조)
• 기본 + 프로젝트 오버라이드 — 리서치 노하우·채점 루브릭은 기본 제공 + 프로젝트 파일로 완전 대체, 거버넌스 수치는 governance.json으로 키별 병합. 프로젝트마다 독립.

디렉토리

prompt-company/                (= 하네스 소스 + 개발/테스트 환경)
  package.json              npm 패키지 (bin: prompt-company / company)
  bin/cli.js                설치 CLI (install --global|--project / init / update)
  CLAUDE.md                 헌법 인덱스 (모든 팀원 자동 로드; 공통 원칙 + 포인터만)
  constitution/             헌법 조항 = 토픽 파편 (art-01..13-*.md)  ← 헌법 10조
  operations/               운영 매뉴얼 = 토픽 파편 (role-mapping, memory-files, meetings,
                            meeting-diversity, signal-model, research-flow, research-knowhow,
                            governance-config, scoring-rubric, ...)
  ORCHESTRATOR.md           리더(=오케스트레이터) 프롬프트
  .claude/
    settings.json           Agent Teams 플래그 + hooks (이 레포 자체 개발용)
    agents/                 역할 = subagent: clarifier · researcher · engineer · designer · reviewer · steward · facilitator · counsel
    hooks/                  session_start(리더지침)·teammate_idle(셀프리뷰)·task_completed(게이트/감사)·observe(이벤트→대시보드)
  memory/                   (프로젝트별 상태 — 이 레포에선 템플릿/테스트용)
    knowledge/  K-XXX.json  공유지식 (1파일=1토픽) + INDEX.md(자동)  ← 헌법 10조
    proposals/  P-XXX.json  수정 제안 + 변론 + 투표 (감사 추적)
    meetings/   M-XXX.json  회의록 (결정·회고·프레임개정) + INDEX.md(자동)  ← 헌법 12조
    decisions/  D-XXX.json  결정 로그 (트레이드오프·reviewer 검토) + INDEX.md  ← 공유지식과 별개
    friction/   F-XXX.json  마찰 로그 (비효율 신호, 진화 입력) + INDEX.md  ← 헌법 13조
    personal/   <직원>/      개인메모리 (git 미추적)
    tasks/      <작업>/      작업메모리 (git 미추적, 임시)
    user_prefs.json         사용자 회의 참석 정책 (헌법 11조)
  orchestration/            kb.py · minutes.py · decisions.py · friction.py (결정적 CLI) · dashboard.py (개발/관측 대시보드)
  reports/                  리서치 리포트 (memory 밖, git 미추적, 임시)
  docs/                     원본 설계 문서 (constitution / design_brief / ...)

설치 & 사용 (npm)

Claude Code v2.1.32+ 필요(claude --version). 런타임에 node(설치 CLI)와 python3 (kb.py·minutes.py)가 필요하다.

설치 — 범위를 고른다

npx prompt-company install            # 대화형: [g] 전역 / [p] 프로젝트 한정 선택
# 또는 명시적으로:
npx prompt-company install --global   # 여러 프로젝트 공용
npx prompt-company install --project  # 현재 프로젝트에 자족적으로

(전역으로 자주 쓸 거면 npm i -g prompt-company 후 prompt-company ... / company ....)

| 범위 | 무엇을 하나 | 언제 | |------|-------------|------| | --global | 역할 → ~/.claude/agents, 하네스 → ~/.claude/company, settings(플래그+훅) 보존 병합. 이후 각 프로젝트에서 prompt-company init(헌법 복사 + 스크립트 shim + memory) | 여러 프로젝트에서 공용으로 | | --project | 현재 폴더에 모든 것(헌법·역할·스크립트·훅·settings·memory)을 복사. 전역 미오염, 자족적 | 이 프로젝트에만, 또는 레포에 커밋해 공유 |

⚠ --global 은 당신의 ~/.claude 전역 설정을 수정한다(역할 추가, 플래그·훅 등록). 두 경우 모두 memory(지식·회의록)는 현재 프로젝트(cwd) 에 쌓인다. 하네스 갱신은 프로젝트에서 prompt-company update(memory 보존).

설치하면 그 프로젝트에서 claude를 켤 때 헌법(CLAUDE.md)이 자동 로드되고 역할을 소환할 수 있다.

갱신 — 최신 버전으로 올리기 (update)

패키지가 새 버전으로 올라갔을 때, 이미 설치한 프로젝트에 반영한다. update는 하네스(헌법· 역할·운영문서·스크립트·훅)만 덮어쓰고 memory/(지식·회의록·결정·마찰)는 보존한다. 설치 모드 (--global 연동 / --project 한정)는 update가 자동 감지한다.

cd <프로젝트>
npx prompt-company@latest update      # 권장: 최신 패키지를 받아 그걸로 갱신

⚠ update는 "지금 실행되는 패키지"를 소스로 복사한다 — 로컬 dev 레포가 아니다. 그래서 전역(npm i -g prompt-company)이나 npx 캐시가 옛 버전이면 옛 버전이 그대로 박힌다. 반드시 @latest를 붙이거나(npx가 최신을 받음), 전역 설치를 먼저 올려라:

npm i -g prompt-company@latest        # 전역 CLI를 최신으로
cd <프로젝트> && prompt-company update  # 그 최신본으로 갱신

| 갱신됨 (force 덮어씀) | 보존됨 (안 건드림) | |------|------| | CLAUDE.md·ORCHESTRATOR.md, constitution/, operations/, orchestration/(--project만), .claude/agents·hooks(--project만) | memory/(knowledge·proposals·meetings·decisions·friction·personal·tasks), user_prefs.json, 프로젝트 오버라이드(governance.json·*.project.md) |

출력에서 복사: CLAUDE.md처럼 파일만 로그에 찍히고 디렉터리(agents/ 등)는 조용히 복사된다 — 로그가 짧아도 역할·운영문서는 함께 갱신된 것이다. 갱신 검증: grep "^tools:" .claude/agents/clarifier.md에 SendMessage 등이 보이고 operations/meeting-diversity.md가 있으면 0.5.x 이상이다. 직접 수정한 헌법·역할은 덮어써지므로 갱신 후 git diff로 확인·커밋하라.

3) 팀 꾸리기 (리더에게 작업만 — 역할 선정은 리더가)

작업만 주면 된다. 어떤 역할을 몇 명 부를지는 사용자가 지정하는 게 아니라, 리더(오케스트 레이터)가 작업을 분석해 스스로 최소 충분 팀으로 정한다(ORCHESTRATOR.md §1). 지식 수정·회의가 필요하면 리더가 facilitator 등을 알아서 소집한다.

ORCHESTRATOR.md 를 따라 오케스트레이터로 행동해줘. "<작업>" 을 처리할 최소 팀을 꾸려 진행하라.

역할을 직접 나열할 필요 없다. 원하면 제약·선호만 덧붙인다 — 예: "디자인 비중이 크다", "외부 리서치가 필요하다". 그래도 최종 팀 구성은 리더가 판단한다.

4) 지식·회의록 다루기 (직원이 CLI로)

python3 orchestration/kb.py list
python3 orchestration/kb.py read K-001 --agent clarifier    # 읽으면 stakeholder 추적
python3 orchestration/kb.py new --author engineer --severity minor \
    --content "클라이언트는 파란색 계열을 선호한다" --reason "킥오프 메모"
python3 orchestration/minutes.py list            # 회의록

직원(에이전트)은 두 설치 모드 모두에서 python3 orchestration/kb.py ... 로 호출한다. 전역 설치 프로젝트엔 orchestration/kb.py·minutes.py 가 shim(전역 로직 호출), 프로젝트 설치엔 실제 스크립트가 깔린다 — 어느 쪽이든 memory는 현재 프로젝트(cwd)에 쓴다. 전체 회의 절차는 orchestration/README.md 와 facilitator 역할 참고.

이 레포 자체에서 개발/테스트할 땐 설치 없이 python3 orchestration/kb.py ... 가 그대로 동작한다.

관측 — 런타임 대시보드

조직이 Agent Teams 위에서 돌 때 무엇이 실제로 호출되는지(역할 소환·태스크·도구/거버넌스 CLI 호출)를 로컬 웹 대시보드로 실시간 관측한다. 설치하면 자동으로 켜진다.

• 계기판 배선 — .claude/hooks/observe.py 가 런타임 이벤트(SubagentStart/Stop·TaskCreated/ Completed·TeammateIdle·PreToolUse·UserPromptSubmit·SessionStart)를 한 줄 JSON 으로 memory/tasks/events.jsonl 에 적재한다. 비차단(exit 0) 이라 정책 훅과 공존하고, 설치 시 자동 배선된다. 끄려면 settings.json 에서 해당 항목을 지운다.
• 대시보드 — 의존성 없는 로컬 웹 뷰어. 좌측 실시간 타임라인 + 우측 거버넌스 보드(제안 투표집계·회의·결정·마찰·공유지식).

python3 orchestration/dashboard.py            # http://127.0.0.1:7878 (브라우저 자동 열림)
python3 orchestration/dashboard.py --port 9000 --no-open

memory/ 는 cwd 기준이라(= kb.py 와 동일) 관측하려는 프로젝트 루트에서 띄운다. events.jsonl 은 git 미추적 런타임 산출물. 팀원↔팀원 SendMessage 직접 훅은 없어 PreToolUse 로 우회 캡처한다.

튜닝 (프로젝트별 오버라이드)

프로젝트마다 cwd에 파일을 두어 기본을 덮어쓴다(없으면 기본값). 프로젝트끼리 독립이고 update가 보존한다.

| 무엇 | 파일 | 방식 | |------|------|------| | 거버넌스 수치(정족수·가결·등급 임계·주 stakeholder 등) | governance.json | 키별 병합 | | 채점 루브릭 | operations/scoring-rubric.project.md | 완전 대체 | | 리서치 노하우 | operations/research-knowhow.project.md | 완전 대체 |

스키마·기본값은 operations/governance-config.md 등 해당 문서 참조.

알아둘 한계 (Agent Teams)

• 실험적 기능. 세션 재개 시 in-process 팀원 미복원, 작업 상태 지연 등 알려진 제한 있음.
• 팀 config(~/.claude/teams/...)는 런타임 자동 생성 — 미리 만들거나 손대지 마라.
• 리더는 고정이며 팀원이 될 수 없다(그래서 orchestrator는 리더 본인 = ORCHESTRATOR.md).
• subagent 정의의 skills/mcpServers frontmatter는 팀원 실행 시 적용되지 않는다.