tmux와 Markdown 스펙을 활용한 병렬 코딩 에이전트

마누엘 쉬퍼는 tmux, 마크다운 파일, bash 별칭, 그리고 여섯 개의 슬래시 명령어를 사용한 경량 설정으로 병렬 코딩 에이전트를 운영해 왔습니다. 이들은 서브에이전트 프로필이나 오케스트레이터 없이 동작하는 기본 에이전트로, tmux 창마다 역할 명명 규칙을 따릅니다: 기획자(Planner, 마크다운 스펙 작성), 작업자(Worker, 완성된 스펙에서 구현), 프로젝트 매니저(PM, 백로그 정리 및 아이디어 덤핑).

기능 설계 시스템

대부분의 코드 작성은 완성된 스펙인 기능 설계(FD)를 바탕으로 이루어집니다. FD는 다음을 포함하는 마크다운 파일입니다:

• 해결하려는 문제
• 고려된 모든 해결책과 각각의 장단점
• 최종 해결책과 업데이트할 파일을 포함한 구현 계획
• 검증 단계

이 시스템을 도입한 후, 쉬퍼는 4-8개의 에이전트와 병렬로 작업할 수 있게 되었습니다. 8개를 초과하면 의사 결정 품질이 저하됩니다. 이 시스템은 300개 이상의 스펙이 있는 한 프로젝트에서 수동으로 구축되었으며, /fd-init 명령어를 사용하여 어떤 저장소든지 설정을 부트스트랩할 수 있도록 새로운 프로젝트로 이식되었습니다.

FD 추적 및 라이프사이클

각 FD는 번호가 매겨진 스펙 파일(FD-001, FD-002...)을 받아 모든 FD에 걸친 인덱스에서 추적됩니다. 파일은 docs/features/에 저장되며 8단계를 거칩니다:

• 계획됨(Planned): 식별되었으나 아직 설계되지 않음
• 설계 중(Design): 해결책을 적극적으로 설계 중
• 열림(Open): 설계 완료, 구현 준비 완료
• 진행 중(In Progress): 현재 구현 중
• 검증 대기 중(Pending Verification): 코드 완료, 런타임 검증 대기 중
• 완료(Complete): 검증 완료, 아카이브 준비 완료
• 연기됨(Deferred): 무기한 연기됨
• 종료됨(Closed): 수행하지 않음

슬래시 명령어

여섯 개의 슬래시 명령어가 전체 라이프사이클을 처리합니다:

• /fd-new: 아이디어 덤프에서 새 FD 생성
• /fd-status: 인덱스 표시: 활성화된 항목, 검증 대기 중인 항목, 완료된 항목
• /fd-explore: 세션 부트스트랩: 아키텍처 문서, 개발 가이드, FD 인덱스 로드
• /fd-deep: 어려운 설계 문제를 탐색하기 위해 4개의 병렬 Opus 에이전트 실행
• /fd-verify: 코드 교정, 검증 계획 제안, 커밋
• /fd-close: FD 아카이브, 인덱스 업데이트, 변경 로그 업데이트

모든 커밋은 해당 FD에 연결됩니다(예: "FD-049: 증분 인덱스 재구현 구현"). 변경 로그는 FD가 완료됨에 따라 자동으로 누적됩니다.

FD 파일 예시

FD-051: 다중 레이블 문서 분류
상태: 열림
우선순위: 중간
노력: 중간
영향: 다운스트림 필터링을 위한 더 나은 재현율

문제
수신 문서는 단일 범주 레이블을 받지만, 많은 문서가 여러 주제를 다룹니다. 분류기가 단일 최적 적합을 강제하기 때문에 다운스트림 필터는 관련 문서를 놓칩니다.
해결책
단일 레이블 분류를 다중 레이블로 대체:

LLM을 사용하여 범주별 신뢰도 점수 할당.
0.90 이상의 신뢰도를 가진 모든 레이블 수락.
모호한 점수(0.50-0.90)의 경우, 확인을 위해 퓨샷 예제를 사용한 두 번째 LLM 패스 실행.
다운스트림 쿼리가 유연하게 임계값을 설정할 수 있도록 모든 레이블과 점수를 저장.

수정할 파일

src/classify/multi_label.py (신규: LLM 기반 다중 레이블 로직)
src/classify/prompts.py (신규: 모호한 경우를 위한 퓨샷 템플릿)
sql/01_schema.sql (점수가 포함된 document_labels 테이블 추가)
sql/06_classify_job.sql (신규: 수집 후 예약된 분류)

검증

스테이징 문서 테이블에서 분류기 실행
운영 로그에 오류가 없는지 확인, 상태 점검 실행
스팟 체크: 알려진 다중 주제 콘텐츠를 가진 문서가 예상 레이블을 가짐
테스트 실행, 다운스트림 필터가 신뢰도 임계값을 준수하는지 확인

시스템 초기화

어떤 저장소에서든 /fd-init을 실행하면:

• CLAUDE.md, 패키지 구성, git 로그에서 프로젝트 컨텍스트 추론
• 디렉토리 구조 생성 (docs/features/, docs/features/archive/)
• 프로젝트에 맞춤화된 FEATURE_INDEX.md 생성
• FD 템플릿 생성
• 여섯 개의 슬래시 명령어 설치
• 프로젝트의 CLAUDE.md에 FD 라이프사이클 규칙 추가

생성된 파일에는 docs/features/FEATURE_INDEX.md (기능 인덱스), docs/features/TEMPLATE.md (FD 파일 템플릿), docs/features/archive/ (아카이브 디렉토리), CHANGELOG.md (Keep a Changelog 형식), 그리고 FD 시스템을 포함한 프로젝트 규칙이 추가된 CLAUDE.md 업데이트가 포함됩니다.