Motifcode의 저장소 구조와 이슈·PR 운영 — 공개 팀 프로젝트와의 비교
Motifcode의 공개 저장소를 읽으며 개발자가 문제를 정의하고 변경을 검토·통합하는 방식을 살펴본 기록이다. DanzzaN은 현직자의 작업 방식을 이해하려고 저장소 구조·이슈·PR 분석을 요청했고, 후속 대화에서 실제 작성 양식, 라벨 활용, 브랜치 규칙의 비교를 추가했다. 특히 Vigilantis는 public 저장소이지만 고정 팀의 프로젝트이므로 외부 기여를 받는 오픈소스 운영과 구분해야 한다고 정정했다.
이 비교에서 보존할 것은 다른 사람이 변경을 이해하고 받아들일 수 있도록 문제·범위·검증 근거를 연결하는 방법이다. Motifcode의 모든 선택을 현직자 전체의 표준이나 Vigilantis가 채택한 규칙으로 취급하지 않는다.
확인 범위와 당시 상태
2026-09-26 GitHub API와 공개 페이지에서 기본 브랜치의 전체 파일 트리, 전체 이슈·PR 목록, PR의 공식 review submission 목록, 주요 본문·댓글·변경 코드, CI 설정·실행 결과와 릴리스 기록을 읽었다. 모든 파일과 PR diff를 전수 코드 리뷰한 것은 아니다.
- 기본 브랜치:
main, 확인 커밋4570d635a6776c12ce281ddeed3aa607ed00a924, 패키지 버전0.3.4. - 이슈: 23개 중 열림 11개·닫힘 12개. 20개는 관리자 계정이 작성했다.
- PR: 14개 중 병합 11개·미병합 종료 1개·열림 2개. 작성 계정은 관리자 포함 7개였다.
- 기본 브랜치의 커밋 84개 중 75개가 관리자 계정 작성으로 표시됐다. squash 등 이력 구성의 영향을 받으므로 노동량이나 개인 기여율로 환산하지 않는다.
- 주요 토론 확인 대상: #8·#9·#25·#29·#33·#34·#35·#37과 이슈 #13·#14. #25·#26은 파일 변경도 확인했다.
- Vigilantis 비교는 당시 로컬 기본 체크아웃의
CLAUDE.md전체와docs/PROJECT_STATUS.md관련 규약, 기존 개인 Vault Atomic을 읽은 범위다. 원격 최신 브랜치나 보호 설정을 별도로 검증한 결과는 아니다.
이 수치와 열린 PR 상태는 당시 관찰이다. 이후 작업의 실시간 현황표로 관리하지 않는다. 분석 과정에서 Motifcode 테스트나 실제 모델 호출을 실행하지 않았다. 코드에 테스트가 존재하는 사실, GitHub CI의 성공 상태, 작성자가 댓글로 보고한 로컬·PTY 검증은 서로 다른 근거다.
공개 여부와 협업 대상
Motifcode에서는 외부 계정의 PR, help wanted·good first issue, 참여 방법을 설명하는 이슈가 확인됐다. 한 명의 관리자가 주도하며 외부 기여를 받는 프로젝트로 읽을 수 있다. 참여자의 직업·고용 상태나 회사 내부 프로세스는 확인하지 않았다.
Vigilantis가 고정 팀의 프로젝트라는 전제는 사용자의 직접 설명이다. 공개 저장소라는 사실은 외부 기여 모집 여부와 별개다.
| 비교 대상 | Motifcode에서 읽을 수 있는 역할 | Vigilantis의 팀 운영 맥락 |
|---|---|---|
| 이슈 본문 | 처음 온 기여자가 문제·시작 위치·완료 조건을 알아가도록 안내 | 팀의 요구사항·담당·접점·의존 작업을 합의 |
| 라벨 | 기술 분류와 함께 참여 가능성·난도·설계 필요성을 표시 | 종류·영역 등의 분류를 담당과 검토 판단에 활용할 수 있음 |
| 브랜치 | 서로 다른 기여자가 작업 내용을 식별하는 이름으로 제출 | 명시적인 TYPE·DOMAIN·이슈번호 규격을 공유 |
| 리뷰 | 관리자가 외부 기여를 검증하고 보완·통합 | 담당 접점과 팀 승인 규칙에 따른 상호 검토 |
이 표의 목적 설명은 사례와 팀 맥락을 비교한 해석이다. 오픈소스이면 명명 규칙이 느슨해야 하거나, 팀 프로젝트이면 반드시 dev가 있어야 한다는 인과관계는 아니다.
저장소 구조와 배포
pnpm workspace는 packages/*를 묶는다. 대부분의 패키지는 src/와 test/를 함께 둔다.
| 위치 | 주된 책임 |
|---|---|
packages/protocol | 모델 요청·응답 형식, 도구 호출 해석·복구 |
packages/core | 실행 루프, 중단·재개, 문맥 압축 |
packages/tools | 도구 스키마와 검사기 |
packages/cli | 명령행 진입점, 설정, 실제 도구 실행과 기능 연결 |
packages/tui | 터미널 출력·입력 처리 |
packages/skills, agents, hooks | 확장 기능 |
packages/journal, replay | 세션 기록·복원, 요청·결과 재현과 오류 주입 |
packages/eval | 벤치마크 실행·채점·보고 |
corpus/, toolkit/ | 기준 데이터와 Python 실험·검증 도구 |
scripts/, .github/workflows/ | 빌드·CI·배포 |
개발할 때는 내부 패키지를 나누고, 사용자용 CLI는 번들로 배포한다. 빌드 스크립트는 workspace 구조가 설치 환경의 의존 조건이 되지 않도록 구성돼 있다.
설치 테스트는 빌드·패키징 후 빈 디렉터리에 설치하고 설치된 명령을 모의 HTTP 서버와 실행한다. 함수의 동작과 별도로 패키지 누락·명령 실행·의존성 문제를 검사하는 구조다. 모의 서버를 사용하므로 실제 모델의 품질이나 실제 공급자 연결까지 보장하지 않는다.
이 구조에서 참고할 점은 폴더 이름 자체보다 변경할 책임과 검증할 위치를 함께 찾을 수 있다는 점이다. 프로젝트 규모와 책임 경계가 다른데 패키지 수만 모방할 이유는 없다.
이슈의 작성 패턴
당시 기본 브랜치에는 별도 이슈 템플릿, PR 템플릿, CONTRIBUTING.md, CODEOWNERS가 없었다. 다음은 공식 양식이 아니라 실제 본문에서 추출한 작성 패턴이다.
| 작업 유형과 원문 | 반복되는 구성과 목적 |
|---|---|
| 작은 버그 #13·#14 | 문제와 구체적 입력·출력, 시작할 코드, 완료 조건, 제외 범위, 검증 방법 |
| 상태 복구 버그 #18 | 확인 버전·커밋, 재현 환경·증거, 아직 관찰하지 않은 영향, 다른 복구 이슈와의 경계 |
| 장기 설계 #22·#23 | 목표·현재 부족한 점·설계 쟁점·단계별 계획·수용 기준. 구현 전에 작은 후속 작업으로 나누도록 안내 |
13은 한🙂을 쓸 때 실제 파일은 UTF-8 기준 7바이트인데 결과 메시지는 문자열 길이인 3을 바이트 수로 표시하는 문제를 다룬다. 완료 조건에는 ASCII·한글·이모지·빈 문자열과 생성·덮어쓰기의 검증이 있고, 파일 내용과 기존 출력 형식을 유지하도록 한다. #26의 실제 diff는 핵심 구현 한 줄과 회귀 테스트다. 완료 조건이 구현 줄 수보다 넓은 동작 범위를 설명한다.
14는 빈 파일, 마지막 개행, 실제 빈 줄을 구별하는 입력·출력 표를 먼저 제시한다. 18은 재개 상태가 전달되지 않은 사실과 실제 외부 작업이 중복 실행됐다는 주장을 구분한다. 발생할 수 있는 영향을 재현에서 관찰한 사실처럼 쓰지 않는 사례다.
작은 버그 이슈의 참고 뼈대는 다음과 같다. 아래 제목을 모두 채우는 형식 준수보다 각 문단이 답할 질문이 중요하다.
## 문제와 재현
어느 버전·환경에서, 어떤 입력·순서로, 무엇이 관찰됐는가?
기대한 결과와 실제 결과는 어떻게 다른가?
## 완료 조건
수정 뒤 어떤 관찰 가능한 결과가 성립해야 하는가?
유지해야 할 기존 동작과 경계값은 무엇인가?
## 범위와 시작점
이번에 다룰 범위, 별도 이슈로 둘 범위, 관련 코드·테스트는 무엇인가?
## 검증
어떤 환경·사례로 확인할 수 있는가?
이미 확인한 결과와 앞으로 실행할 검사는 무엇인가?good first issue는 수정 줄 수만 뜻하지 않는다. #13·#14는 기대 동작과 범위가 정해져 있지만 18은 상태 복구와 이미 실행한 작업을 다루므로 첫 기여용으로 분류하지 않았다. 모호성과 실패 비용까지 고려한 분류로 읽힌다.
PR의 작성 패턴과 검토 기록
작은 수정 PR은 변경 전후 동작, 연결 이슈, 검증 결과를 짧게 담는다. 복잡한 수정은 호환성·실행 경계·검토 요청 지점을 더한다.
| 사례 | 본문에서 참고할 것 |
|---|---|
| #26 | 바이트 표시 변경, 회귀 범위, Windows에서 남은 기존 실패 |
| #9 | 첫·둘째 응답의 조건과 변경 효과, 원래 코드와 비교한 실패 결과 |
| #25 | 상태 복구와 출력 계약, 제외한 journal 경로 문제 |
| #33 | 불확실한 쓰기·이전 기록 호환성·여러 재개 진입점, 재현에서 입증한 영향의 범위 |
## 변경 결과
어떤 문제에서 사용자에게 보이는 동작이 어떻게 바뀌는가?
## 변경 범위
핵심 수정과 호환성·관련 이슈. 큰 변경이면 검토할 접점을 추가한다.
## 검증 결과
실행한 검사와 결과·환경.
미실행·실패·기존 실패와의 비교·남은 한계.
## 관련 이슈
해당 저장소의 연결·종료 규칙에 맞춘 참조.이 뼈대는 사례에서 추출한 제안이다. Motifcode의 공식 PR 템플릿이나 Vigilantis 템플릿의 대체물이 아니다. Vigilantis는 당시 개요·변경 사항·테스트·관련 이슈의 네 섹션과 리뷰 요청 줄을 규정하고 있었다.
실패 결과를 설명하는 방식
9의 기여자는 Windows 전체 테스트가 실패했다고 적고, 원래 구현에서도 같은 실패들이 재현되며 새 회귀 사례가 추가로 실패한다는 비교 결과를 보고했다. 관리자는 자기 환경·CI·설치된 패키지의 검증 결과를 댓글로 남겼다.
이 기록은 기존 실패를 무시해도 된다는 규칙이 아니다. 기존 문제라는 판단에 환경·비교 근거가 필요하고, 일부 통과를 전체 통과라고 쓰지 않는 사례다. 체크되지 않은 검증 계획과 실제 실행 결과도 구분한다.
관리자 보완과 기여자 재확인
25에서는 관리자가 후속 커밋으로 재개 진단 메시지를 stderr로 옮기고 --print·-p의 출력 테스트를 보강했다. 원래 기여자의 확인을 받은 뒤 최신 main과 합친 결과도 검증했다고 보고하고 병합했다. 리뷰가 지적 전달뿐 아니라 결과물을 함께 완성하는 과정으로 나타난다.
#29에서도 관리자가 추가 수정한 뒤 기여자가 다른 터미널 환경에서 확인했다. 검토 과정에서 발견한 별개 문제는 #30·#31·#32로 분리했다.
중복 PR의 조정
#34와 #35는 같은 문제를 거의 동시에 다뤘다. 관리자는 두 PR을 잠시 유지하며 한쪽에만 있는 변경·테스트를 비교하자고 제안했다. 기여자는 옮길 추가 내용이 없다고 판단하고 35를 닫았다. 비교·조정의 사례이며 모든 중복 PR을 같은 절차로 처리해야 한다는 규칙은 아니다.
라벨과 브랜치가 드러내는 정보
라벨은 서로 다른 축을 조합한다.
| 축 | 실제 라벨 | 판단에 주는 정보 |
|---|---|---|
| 종류 | bug, enhancement | 결함 수정인지 기능 개선인지 |
| 영역 | area:runtime, area:tools, area:ux, area:mcp, area:skills | 영향을 받는 영역 |
| 우선순위 | priority:P1·P2·P3 | 우선순위 구분. 전체 등급 정의까지 확인한 것은 아님 |
| 참여 | help wanted, good first issue | 외부 도움이 필요한지, 첫 기여에 적합한지 |
| 설계 | needs-design, roadmap | 구현에 앞서 논의·분할이 필요한지 |
#30은 버그·영역·우선순위·도움 요청·첫 기여 라벨을 함께 사용한다. 조회한 PR 대부분에는 라벨이 없고 #36·#37에 일부 붙어 있어, 적극적인 활용은 이슈 쪽에 더 뚜렷했다.
help wanted와 good first issue는 낯선 외부 참여자에게 특히 유용하다. 고정 팀이 이 라벨들을 그대로 도입할 필요는 없다. 종류·영역·우선순위를 구분하는 생각은 다른 협업 환경에서도 참고할 수 있지만, 실제 운영 효과를 이 분석에서 측정하지는 않았다.
브랜치는 작업 내용을 이름으로 식별한다는 점에서 유사하지만 명시적 규격과 통합 경로는 다르다.
| 항목 | Motifcode의 당시 기록 | Vigilantis의 당시 규약 |
|---|---|---|
| 이름 | fix/27-unchanged-footer-redraw, fix-13-utf8-byte-count, issue-18-print-resume-checkpoint, codex/fix-7-uncertain-write-resume 등 혼재 | <type>/<DOMAIN>-<이슈번호>-<english-kebab-summary>; 이슈가 없으면 번호 생략 |
| 작업 PR 대상 | 조회한 14개 모두 main | 기능 작업은 dev 기준, PR도 dev; main은 안정·배포 기준 |
| 이슈 연결 | Fixes·Closes로 자동 종료 활용 | Refs로 연결하고 머지 책임자가 완료 여부를 판단해 수동 종료 |
| 리뷰 표현 | 공식 review submission 14개 PR 모두 없음; 주요 검토·확인은 Conversation 댓글 | 승인 또는 변경 요청을 공식 리뷰 상태로 표현하도록 규정 |
Motifcode의 명명 방식은 관찰된 관행이지 강제된 브랜치 규칙으로 확인된 것이 아니다. 브랜치 보호·필수 승인 설정도 확인하지 않았다. Vigilantis의 규약은 팀 문서를 원천으로 삼으며 이 노트가 대신 관리하지 않는다. TYPE·DOMAIN과 종류·영역 라벨은 유사한 분류 질문에 답하지만 표기 위치와 운영 목적은 다를 수 있다.
이슈부터 배포까지의 연결
#14에서는 기여자가 재현·수정안을 댓글로 제시하자 관리자가 PR과 Fixes #14 연결을 요청했다. #24가 squash merge된 뒤 이슈에 수용 조건의 확인 결과와 CI 링크를 남겼다. 당시에는 main 반영과 npm 미배포를 구분했고, 나중에 0.3.3 릴리스가 배포된 변경과 기여자를 연결했다. #13 → 26도 같은 연결을 보여준다.
자동 종료와 수동 종료 중 하나를 보편적 정답으로 정할 근거는 없다. 이 사례에서는 작은 이슈 전체의 수용 조건을 확인했다는 기록과 자동 종료를 함께 읽어야 한다. 자동 종료 사건 자체가 기준 충족이나 npm 배포를 증명하지 않는다.
CI 설정은 Node 20·22의 타입 검사·빌드·테스트·도구 스키마 검사, Linux ARM64 빌드·테스트, Python 테스트, 기준 fixture 재생성을 수행한다. 당시 릴리스 커밋 CI의 다섯 작업 성공 상태를 직접 확인했다. Windows·macOS 자동 작업은 해당 설정에 없었다.
릴리스 워크플로는 버전 태그를 계기로 다시 검사하고 태그·패키지 버전 일치를 확인한 뒤 npm 게시와 GitHub 릴리스를 수행한다. 0.3.4 실행의 성공 상태도 확인했다. 릴리스 노트에 있는 별도 레지스트리·설치 검증과 번들 해시 일치 보고를 이번 분석자가 재실행한 것으로 표현하지 않는다.
기록을 모범 규칙으로 일반화하기 어려운 부분
- 당시 열린 #37은 MCP와 스킬 관리 등을 묶어 90개 파일·9,930줄 추가·12개 커밋으로 커졌다. 로드맵의 작은 단계 지향과 실제 PR 규모 사이의 차이다. 해당 head CI는 성공했지만, 이 사실만으로 설계·상호작용이 충분히 리뷰됐다고 판정할 수 없다.
- #33·#34에는 공지한 검토 기한보다 일찍 병합했다는 기록이 있다. 검토 기간을 엄격한 강제 규칙으로 운영한다고 볼 근거는 없다.
- 검토 내용이 자세한 것과 공식 승인 절차·보호 설정이 있다는 것은 별개다. 일반 댓글에서도 실질적 검토가 가능하지만 승인 상태의 표현 방식은 Vigilantis와 다르다.
- #10 등에는 AI 보조 사용이 명시돼 있다. 상세한 기록을 모두 사람이 수작업으로 수행했다는 증거로 읽지 않는다.
- 관리자에게 문제 정의·추가 검증·병합·배포가 집중된다. 규모가 커졌을 때의 분담이나 지속 가능성을 이 기록만으로 입증하지 않는다.
기존 지식과 연결
- 요구사항의 변경 영향은 설계·구현·검증 연결로 추적한다: 이슈의 기대 결과를 구현·테스트·릴리스에서 다시 찾는 사례.
- PR 머지와 Issue 완료 판정을 분리한다: 수용 기준을 확인한 자동 종료와 팀의 수동 종료 선택, 배포 시점의 별도 기록.
- 규칙은 소유한 가장 좁고 안정적인 공개 경계에서 깊게 테스트한다: 실행기 회귀와 설치된 제품 검사가 추가하는 증거.
- 요구사항에서 검증까지: 요구 정의부터 결과 판정까지 이어 읽는 입구.
이 문서는 비교와 학습 기록이다. DanzzaN이 증류를 요청한 사실을 특정 라벨·브랜치·리뷰 방식을 팀 규칙으로 채택한 승인으로 확대하지 않는다.