feat(harness): Memo 패턴 — 분산 슬롯 + 공유 헤더 (선택)

[namojo]

배경 및 동기

장기 작업, /clear로 인한 세션 재개, 자동 컴팩트(auto-compact)로 인한 컨텍스트 유실은 하네스의 두 가지 비용을 발생시킵니다.

1. 직접 비용 — 토큰 낭비: 세션을 다시 시작할 때마다 같은 자료(코드, 결정 이력, 진척)를 다시 읽어 들이며 토큰을 반복 소비합니다.
2. 간접 비용 — 컨텍스트 유실: 컴팩트 직후 에이전트가 방금 자기가 무엇을 했는지 모르는 상태가 되어, 같은 결정을 두 번 내리거나 이전 결정을 모순되게 뒤집습니다.

기존 메커니즘으로는 이를 충분히 해결하지 못합니다.

• TaskCreate/TaskUpdate는 진행 상태(pending/in_progress/completed)에 강하지만 왜 그렇게 결정했는가를 담지 못합니다.
• SendMessage는 실시간이고 영속이 아니며, 컴팩트되면 사라집니다.
• _workspace/는 중간 산출물의 원본이지만 양이 많아 매 세션 전체를 읽기에는 비싸고, 결정 요약이 없어 빠른 흡수가 어렵습니다.
• MEMORY.md(auto memory)는 사용자 보편적 영속 메모리이며, 프로젝트별·세션별 진척을 담는 곳이 아닙니다.

이 PR은 위 빈 칸 — 프로젝트별·세션 간 영속되는 결정 + 진척의 압축 요약 — 을 채우는 선택적 권장 패턴을 도입합니다.

무엇을 추가하는가

skills/harness/references/memo-pattern.md (신규, 약 280줄)를 추가하고, skills/harness/SKILL.md의 Phase 1에 선택적 권장 패턴 판단 단계를, 참고 섹션에 항목을 1줄씩 추가합니다.

핵심 구조 — 분산 슬롯 + 공유 헤더

```
<프로젝트>/.harness/
├── status.md ← 공유 헤더 (팀 전체 목표 + 합의된 핵심 결정만)
├── agents/
│ ├── {agent-1}.md ← agent-1만 쓰는 자기 영역 (독립)
│ └── {agent-2}.md ← agent-2만 쓰는 자기 영역 (독립)
└── archive/ ← 압축된 옛날 내용 (필요 시)
```

라이터 분리:

액션	누가	어디에
공유 헤더(`status.md`) 갱신	오케스트레이터/리더만	Objective, Phase Progress, Team Decisions
자기 슬롯 갱신	본인만	자유롭게
다른 에이전트 슬롯 읽기	누구나	협업 필요 시에만

이 분리로 lockfile이 구조적으로 불필요합니다. 라이터 경합이 발생하지 않습니다.

마일스톤 갱신 정책

매 도구 호출마다 갱신하면 오히려 토큰을 더 씁니다. 다음 시점에만 갱신합니다.

시점	누가	어디에
작업 시작	본인	자기 슬롯의 `Current Task` 1줄
Phase 완료	본인	자기 슬롯 `Accomplishments` append + 리더에 SendMessage
팀 합의/Phase 전환	리더	공유 헤더 `Phase Progress` + `Team Decisions`
에러 발생	본인	자기 슬롯 `Issues` + 리더에 SendMessage
일반 Edit/Read/Bash	—	갱신 안 함

다른 메커니즘과의 역할 분리

메커니즘	무엇을 다루나	Memo와의 관계
TaskCreate	진행 중 작업 상태	Memo는 완료 후 핵심 산출 요약만
SendMessage	실시간 협업·요청·알림	Memo는 영속 결정만
`_workspace/`	중간 산출물의 원본	Memo는 산출물의 포인터만
`MEMORY.md`	사용자/feedback/project 영구 메모리	Memo는 프로젝트별·세션별
git log / 코드	구현 결정 변경 이력의 진정한 원본	Memo는 결정의 요약만

원칙: Memo에는 "이미 다른 곳에 있는 정보의 위치 포인터 + 한 줄 요약"만 둡니다. 디테일을 복사하지 않습니다.

충돌 시 우선순위

```
코드 자체 > git log > TaskCreate 상태 > _workspace/ 산출물 > .harness/status.md
```

Memo는 요약·캐시이지 원본이 아닙니다. 충돌 시 코드를 신뢰하고 Memo를 정정합니다.

압축·폴딩

각 슬롯이 200줄을 넘으면 오래된 `Accomplishments` 상위 50%를 한 줄로 폴딩하고, 원본은 `archive/{agent}-{yyyy-mm-dd}.md`로 이동시킵니다.

적용 기준 (default는 적용 안 함)

적용 권장	적용 비권장
작업이 30분 이상 이어질 가능성	단발성 자동화
`/clear`·세션 재개·다음날 이어 작업 가능성	한 번에 끝나는 산출물
에이전트 4명 이상 + Phase 3개 이상	에이전트 1~2명, 단일 Phase
코드베이스 마이그레이션·장기 리서치·다단계 빌드	짧은 변환·요약

Phase 1에서 도메인 특성을 보고 적용 여부를 판단합니다. 적용 시 사용자에게 1줄로 알립니다.

적용 예시

문서에는 "Express 4 → Fastify 4 단계적 마이그레이션" 시나리오로 5명 팀(orchestrator + dependency-analyst + route-rewriter + test-updater + regression-checker)의 `status.md`와 슬롯 발췌, 다음 세션 재개 흐름을 보여줍니다.

흔한 안티패턴 (8개)

매 Edit/Bash 후 갱신, 한 사람이 모든 슬롯 갱신, Decisions 항목 삭제, 산출물 본문을 status에 복사, TaskCreate를 status로 대체, status에 사용자 보편 사실 기록, `.harness/`를 git에 commit하지 않음, `.harness/`에 secrets/credentials 기록 — 모두 문서에 "왜 금지인가"와 함께 명시.

변경 사항

• 신규: `skills/harness/references/memo-pattern.md` (281줄)
• 수정: `skills/harness/SKILL.md`
  • Phase 1에 6. 선택적 권장 패턴 적용 여부 판단 단계 추가
  • `## 참고` 섹션에 Memo 패턴 1줄 추가

후속 PR

본 PR로 도입된 Memo 패턴을 자동화(SessionStart/PreCompact hook으로 status 자동 주입)하는 후속 PR "Hook 통합 (선택)"을 별도로 제안할 예정입니다. 자동화는 위험한 책임이므로 별도 PR로 분리하여 사용자 명시 승인이 있을 때만 적용되도록 합니다.

체크리스트

• 신규 파일은 references/ 하위에 배치 (조건부 로딩)
• SKILL.md 본문에는 판단 트리거 + 포인터만 추가, 디테일은 references/로
• default가 "적용 안 함"임을 SKILL.md와 references/ 양쪽에 명시
• 기존 메커니즘(TaskCreate/SendMessage/_workspace/MEMORY)과 역할 분리표 명시
• 안티패턴 + 적용 체크리스트 포함