b3os-sf git:20261003.e9195f7A

Immutable. This exact content never changes and is served at /api/v1/blob/c3fc52ce23a619e0.

---
name: b3os-sf
description: "b3os SF(Software Factory) — 프로젝트 방법론. b3rys 팀원이 ★프로젝트★(단순 리서치·프로토가 아닌, 팀장 요구가 여러 번 쌓이는 일)를 맡았을 때 항상 하는 관리·보고 스킬. 팀장 지시를 빠짐없이 목록으로 잡고(TODO.md 정본), 칸반 카드와 맞추고, 채널별(텔레그램·슬랙·팀버스·저장소) 정해진 모양으로 보고한다. 사용 시점 — 팀장이 '목록으로 관리해', '정리해서 보내봐', '다 처리했어?' 라고 할 때, 프로젝트 킥오프·마일스톤·인계 때."
owner: steve
trigger: run a project (many lead requests over time)
---

# b3os SF (Software Factory) — 프로젝트 방법론

## 언제 작동?
- 팀장 요구가 ★여러 번 쌓이는 일★ — 앱·서비스·긴 기능. 단발 리서치·프로토는 대상 아님 (그건 `b3os-task-loop` 카드 하나로 충분).
- "목록으로 관리해" · "정리해서 보내봐" · "다 처리했어?" · "지금까지 나온 말로 정리하자".
- 킥오프 · 마일스톤 · 배포본 전달 · 다른 팀원에게 인계.

## 한눈에 — 시작 · 개발 · 운영

```
① 시작(한 번)        요구 정리★(팀장 첫 기능 목록 → 팀원 구체화 · 상세 기획서 없이, 기능은 개발하며 붙는다) → 초기 설계★(구조 그림·기술 선택, 팀원 리뷰)
                     → 뼈대(저장소 · README·DESIGN·FEATURES·TODO · CI · projects.json 한 줄 · 칸반 카드 · 에이전트 팀) — 첫 PR 부터 리뷰
                                                              → 이 스킬 · references/agent-team-by-domain.md
② 개발(요청마다)     요 만 검 리 문★ 내 보★ 배
                     요청 → 만들기 → 검사 → 리뷰 → 문(머지 승인) → 내보내기 → 보고(실사용 확인) → 배우기(TODO·노하우·설계 문서)
                                                              → b3os-bwf · b3os-github-workflow · b3os-release-ops · b3os-team-learning-loop
③ 운영(내보낸 뒤)    감시(살아 있나·느려졌나 자동 확인, 이상하면 알림) · 장애(되돌리기 먼저 → 원인 → 고침은 ②로)
                     · 정비(의존성·런타임 업데이트는 백업 후) · 피드백(사용 중 요청·버그 → ② 요청으로)
                                                              → b3os-release-ops
★ = 팀장 확인(시작: 첫 기능 목록·초기 설계 · 개발: 머지 승인·실사용)
```

## 방법론 — 여섯 원칙

1. **요청 원문으로 추적한다.** 팀장의 말은 원문 그대로 목록에 남고, 출시 보고도 그 원문별로 쓴다. 요청이 개수나 요약으로 접히면 무엇이 빠졌는지 아무도 모른다.
2. **검사가 머지와 출시를 막는다.** 사람의 "괜찮아 보인다" 대신 정해진 검사의 통과·실패로 판정한다. 검사가 흔들리면 검사부터 고친다.
3. **만든 AI 와 리뷰하는 AI 를 나눈다.** 모델·도구가 다른 팀원이 리뷰한다. 같은 AI 는 같은 실수를 같이 놓친다.
4. **사람은 정해진 지점에서만, 그러나 반드시 확인한다.** 방향(기능 목록·설계)과 결과(머지·실사용)만 사람이 보고, 그 사이는 AI 팀이 끝까지 끈다.
5. **사실로 보고한다.** 잰 것과 못 잰 것을 나누어 쓴다. 못 잰 것은 통과로 세지 않고 "사람이 볼 것" 으로 넘긴다.
6. **배운 것은 다음 일의 입력이 된다.** 노하우를 문서·스킬로 남기고, 다음 프로젝트는 그것을 읽고 시작한다.

## 지식·노하우 — 무엇을 어디에 쌓나

| 무엇 | 어디 | 누가 다시 쓰나 |
|---|---|---|
| 요청과 상태 | `TODO.md` (원문 · `[x]` 완료 · `[~]` 진행 · `[ ]` 미착수) | 출시 보고 도구가 이 목록에서 보고 뼈대를 만든다 |
| 되는 기능 | `FEATURES.md` | 새 팀원·리뷰어가 범위를 확인 |
| 구조 | `DESIGN.md` (그림 포함) | 큰 변경 전 리뷰 기준 |
| 프로젝트 노하우 | 저장소의 노하우 문서 (속도·함정·재는 법, 근거 커밋·수치와 함께) | 같은 프로젝트의 다음 작업 |
| 팀 공통 교훈 | 팀 공유 기록 → 주간 검토 → 팀 공통 규칙으로 승격 | 모든 프로젝트, 모든 AI 팀원 |
| 방법 자체 | **이 스킬(b3os SF)** | 프로젝트를 시작하는 모든 팀원 |

★살아 있는 스킬★ — 프로젝트 단계가 끝날 때마다 배운 것을 여기 반영한다.

## 정본은 둘, 뷰는 여럿

| 무엇 | 정본 | 어디 |
|---|---|---|
| 팀장 지시·결함·킵 목록 | `TODO.md` | ★프로젝트 저장소 루트★ (git 동기화) |
| 과제 상태 (plan/doing/done) | 칸반 `task` 카드 | `team.db` (`b3os-task-loop`) |
| 채널 보고 | 위 둘에서 만든 ★뷰★ | 텔레그램·슬랙·팀버스 |

★같은 사실을 두 곳에 다른 값으로 적지 않는다.★ 보고문을 손으로 고쳐 쓰다 TODO.md 와 어긋나면 정본이 둘이 된다. 보고는 TODO.md 를 읽어 만든다.

## 처음부터 끝까지 — 단계와 산출물

| 단계 | 하는 일 | 산출물 (어디에) |
| --- | --- | --- |
| 1 요구 | 팀장 메시지 하나 = TODO 항목 하나 이상(요지·시각·사진). 킵은 `📌 킵` 절, 착수 안 함. 방향이 바뀌면 지우지 않고 "HH:MM 뒤집음" | `TODO.md` |
| 2 실행 | 10분 단위 마일스톤. 큰 과제면 칸반 카드 갱신(다음 액션·재개 시각·fallback). 하네스: 계약 → 모듈 병렬 → 통합 → 아키·검증 → 게이트 → 배포/공증. 긴 작업은 30분 단위로 진행 두 줄(마일스톤·지연·막힘이 없으면 생략) — 보고를 빚진 긴 작업은 expect-report 등록 | PR(리뷰·머지 게이트) · 검증 근거 폴더(`docs/acceptance` — 기능별 케이스 ↔ 검사 파일 매핑과 인수 매니페스트) · 카드 description |
| 3 산출물 자리 | 코드·문서 = 저장소 / 상태 = TODO `[~][ ][x]` + 칸반 lane / 검증 근거 = 저장소의 검증 근거 폴더(예: `docs/acceptance`) / 리서치·발표 = `/reports` / 화면 = Projects 탭이 저장소 md 를 자동으로 보여 준다 — 프로젝트 상태 보고서를 따로 만들지 않는다. 기능이 바뀌면 FEATURES, 구조가 바뀌면 DESIGN, 작업 근거는 TODO | 저장소 · Projects 탭(뷰) |
| 4 닫기 | TODO `[x]` + 카드 done + FEATURES 반영 + 배포/공증 링크. 배운 규칙은 스킬에, 실수는 메모리·SHARED.md 에(저장소엔 안 남김) | 스킬 PR · SHARED.md |

Projects 탭(`docs/PROJECTS_TAB.md`)이 TODO 의 `[~]` 를 "진행중" 으로 센다 — ★끝난 항목을 `[~]` 로 두면 탭 숫자가 거짓이 된다.★ 상태는 바뀌는 순간 갱신한다.

## 목록 규율 — 팀장이 말한 것은 ★전부★ 들어간다

1. 팀장 메시지 하나 = 항목 하나 이상. 지시의 ★요지를 그대로★ 적고 시각(KST)·메시지 id·사진 경로를 단다. 요약만 남기면 나중에 "이게 무슨 얘기야" 가 된다. (TODO.md 는 프로젝트 저장소 안에 있으므로 그 저장소의 공개 여부에 따라 인용 수위를 맞춘다 — `b3os-github-workflow`.)
2. 상태는 셋 — `[ ]` 미착수 · `[~]` 진행중 · `[x]` 완료. 상태가 바뀌는 ★그 순간★ 갱신한다. 세션 끝에 몰아서 하지 않는다.
3. 팀장이 "킵" 이라 하면 `📌 킵` 섹션에 넣고 ★착수하지 않는다.★ 설계 논의가 나와도 착수 지시가 아니다.
4. 팀장이 방향을 바꾸면 옛 항목을 지우지 말고 ★"HH:MM 에 뒤집음"★ 을 달아 둔다.
5. 내가 찾은 결함도 같은 목록에 ★"<담당> 이 찾음"★ 표시로 넣는다. 팀장 것과 섞이면 누가 시켰는지 잃는다.
6. 내가 틀린 것은 ★저장소가 아니라 메모리(개인)·SHARED.md(팀 학습)에★ 적는다. 회고는 저장소에 남기지 않는다.

## TODO.md 모양 (프로젝트 저장소)

```markdown
# <프로젝트> — 작업 트래커
`[x]` 완료 · `[~]` 진행중 · `[ ]` 미착수

## 🎯 지향점 · 목표
## 🧱 정해진 구조 · 상시 기준
## 🔄 팀장 피드백 (YYYY-MM-DD HH:MM KST) — <담당> 관리      ← 팀장 메시지 묶음마다 하나
   - [ ] 항목 — 요지 · 사진 경로 · 원인(후보/확정) · 검증 기준
## 📌 킵 — 착수 안 함
## 🐛 별건 결함 — 검증 중 나온 것
## 🖐 팀장 손 검증 — 시험으로 못 재는 것
```

## 채널별 보고 포맷 — `references/channel-formats.md` 가 정본

| 채널 | 언제 | 모양 | 길이 |
|---|---|---|---|
| **텔레그램 1:1 · 정리** | "정리해서 보내봐" · 마일스톤 | ★상태별 구획(━━━) + 항목 앞 상태 아이콘 반복★ (아래) | 화면 두 번 스크롤 안 |
| **텔레그램 1:1 · todo 리스트** | "todo 리스트 줘" · 중간 목록 | ★`[영역 — 버전]` 머리 + 번호 이어 매김 + 줄 끝 ` — 상태 ✅`★, 끝에 ❓ 결정 대기 | 한 화면~두 화면 |
| **텔레그램 1:1 · 빌드 전달** | 공증본·배포본을 보낼 때마다 | ★요청 대조표★ — 팀장 요청 원문(따옴표)별 번호 + `— ✅/⏸ 바뀐 것 한 줄`, 요청 밖 고침은 `[내부]`, 끝에 꼭 알아야 할 것 한 줄 (아래) | 한 화면 |
| **텔레그램 1:1 · 진행** | 진행 알림 · 질문 답 | ★두 줄★ — 무엇 → 어디 → 다음 | 2~5줄 |
| **슬랙** | 팀 공지·인수인계 | `b3os-slack-format` | 그 스킬대로 |
| **팀버스 (팀원)** | 위임·검토 결과 | `[태그] 한 줄 결론` + 근거 — CLAUDE.md 핵심룰(member↔member = function call) 그대로 | 인사·감사 없음 |
| **저장소 (커밋·PR)** | 병합 | `b3os-github-workflow` — 핵심 3~5줄 + 사실·인과만 | 회고·의견 없음 |

★텔레그램 정리 포맷★ — ★상태별 구획 + 항목 앞에 같은 상태 아이콘 반복.★ 실물은 `references/channel-formats.md`. 구획마다 다른 아이콘을 달면 읽기 어렵다는 반응, 아이콘을 다 빼면 원하는 모양이 아니라는 반응이 온다 (둘 다 실측).

```
✦ <프로젝트> 지금 상황입니다.
━━━━━━━━━━━━━━━━━━━━
🟥 ★고치는 중 · 우선순위 1★ (n)
━━━━━━━━━━━━━━━━━━━━
🟥 항목
🟥 항목
━━━━━━━━━━━━━━━━━━━━
✅ ★드린 앱에 있음★ (n)
━━━━━━━━━━━━━━━━━━━━
항목 · 항목 · 항목
━━━━━━━━━━━━━━━━━━━━
⚪ ★킵★ (n)   /   👆 ★눌러봐 주셔야 하는 것★ (n)
```

★텔레그램 진행 알림★ — 두 줄. 상세는 PR 본문·TODO.md 에 있으니 다시 적지 않는다.
```
<무엇> → <어디에 올림/들어감>, <다음>.
```

## 도메인별 에이전트 팀 — `references/agent-team-by-domain.md`

프로젝트를 열 때 에이전트 팀을 설계하고(만드는 역할 N · 판정하는 역할 · 통합하는 역할 + 공통부 주인 1명), 진행 단계마다 관리한다(각도가 늘면 역할 추가, 한 역할이 두 일을 하면 분리, 병목이면 주인 이동, 단계 전환이면 재설계). 실사용 단계(신고·결정이 실시간으로 올 때)는 모듈 축 위에 역할 축(🐞 버그·🛠 구현·✅ 검증)을 얹고 지시는 한 번에 묶는다(§3). 역할 정의는 프로젝트 저장소 `.claude/agents/` 에 파일로. 도메인 예시: 프로그램 개발 · 영상 · 콘텐츠 · 금융/제조 분석. 짜는 법의 정본은 `b3os-harness-playbook`.

## 보고 규율

- 위임 뒤 대기는 `b3os-task-loop` 의 wait record(`recheck_at` · `fallback` · `escalation_after`)를 쓴다. 배달 성공은 일 시작이 아니다 — ★답장만이 신호★ 이고, 리듬을 넘기면 팀장에게 알린다.
- "다 처리했어?" 에는 ★숫자로★ 답한다 — "21건 중 19건". 남은 것과 막힌 이유를 같이.
- 내가 못 잰 것은 ★"못 쟀다"★ 라고 쓴다. 통과로 세지 않는다. 팀장 손 검증 목록으로 넘긴다.
- 배포본을 줄 때는 ★눌러볼 것★ 목록을 같이 준다 — 내가 못 잰 자리가 곧 팀장이 볼 자리다.

## 빌드 전달 보고 — 빌드마다 같이 하는 것

빌드(공증본·배포본)를 보낼 때마다 아래를 ★같은 묶음★으로 한다. 빌드를 만드는 동안(공증·검사 대기) 별도 브랜치에서 해 두고, 빌드가 끝나면 합친다.

1. **요청 대조표 메시지** — 사람이 쓴다. 검사 스크립트가 만든 요약 줄(안 잰 것·판정 한계·커밋 판정 등)은 메시지에 넣지 않는다 — 맥락 없는 기계 말로 읽힌다. 그런 줄은 빌드 산출물 파일에만 둔다.
   ```
   <앱> <버전> 공증본입니다 (<sha>)

   [요청]
   1. "<팀장 원문>" — ✅ <바뀐 것 한 줄, 사용자 말로 · 파일·커밋 이름 없이>
   2. "<팀장 원문>" — ⏸ <미룬 이유 한 줄>
   [내부]
   3. <요청 안 했지만 바뀐 것> — ✅
   꼭 알아야 할 것: <있을 때만 한 줄 — 예: 검사를 못 넘겼는데 손으로 냈다(이유)>
   ```
   - 같은 요청이 TODO 줄·커밋 제목·머지 제목에 여러 번 나와도 ★한 줄★. 개수로 접지 않는다(요청이 안 보이게 된다).
   - 도구는 ★뼈대만★ — 요청 원문 목록·상태·요청 밖 커밋 후보를 뽑아 빠뜨림을 막고, 문장은 사람이 쓴다.
2. **TODO.md 갱신** — 이번 빌드에 든 요청을 `[x]`(원문 인용), 남은 것·보류는 이유와 함께.
3. **노하우 문서 갱신** — 이번 빌드에서 배운 것(속도·함정·재는 법)을 근거(커밋·수치)와 함께 프로젝트 노하우 문서에 쌓는다. 같은 일을 되풀이하지 않게.
4. **설계 문서 갱신** — 이번 빌드로 구조·동작 방식이 바뀌었으면 DESIGN.md 등 설계 문서를 같이 고친다(바뀐 곳과 이유 한 줄). 안 바뀌었으면 하지 않는다.

## PM 진행 점검 — 작업 단위(10분)마다

**원칙: 규칙과 점검은 같이 간다.** 이 스킬이 PM 이 프로젝트를 관리하는 규칙을 정하고, PM 이 그 규칙대로 하는지는 ★PM 밖의 점검 스케줄 잡★ 이 따로 잰다. PM 의 자기 점검만 믿지 않는다.

PM 은 보고를 기다리지 않고 ★실제로 움직이는지★ 를 작업 단위 주기로 잰다. 기본 단위가 10분이면 10분마다.
- **걸기:** 세션을 열거나 다시 시작하면 바로 주기 점검을 건다(예: Claude 는 `CronCreate` 로 `3,13,…,53 * * * *`). 크론은 세션 한정이라 세션마다 다시 건다.
- **재는 것:** 가지별 마지막 커밋 시각(`git for-each-ref --sort=-committerdate`) · 에이전트·팀원 상태(ListAgents 등) · 공유 자원 점유(앱 창·빌드 슬롯). 팀원의 보고가 아니라 ★커밋·산출물 시각★ 으로 본다.
- **10분 움직임 없음** → 담당에게 한 줄 상태를 묻는다(무엇을 돌리는 중 / 무엇을 기다리는 중 / 막힘).
- **20분 움직임 없음**(10분 물음에 답이 없거나, 담당이 말한 끝 시각이 지났을 때만 — 커밋 없이 도는 측정·출시 검사·빌드는 움직임으로 친다) → 넘겨받아 새 에이전트로 병렬 재배치하고, 원래 담당에게 "넘겨받음 · 미커밋분은 커밋해 sha 로" 를 알린다. 넘기기 전에 담당의 다른 가지에 이미 한 일이 없는지 먼저 찾는다(중복 작업 방지).
- **끝난 가지** → 기다리지 않고 바로 다음 단계(리뷰·통합·검사)로 넘긴다.
- **공유 자원 대기열**(한 번에 하나만 쓰는 앱 창 등)은 PM 이 순서를 정하고, 앞 차례가 멈추면 같은 규칙으로 다음에 넘긴다.
- 바뀐 게 없으면 PM 세션(터미널)에 한 줄만 남긴다 — 팀장·팀원에게 보내지 않는다.

**PM 점검 잡(PM 이 잘 하는지):** 프로젝트를 열 때 PM 은 `b3os-scheduler` 로 durable 잡을 같이 건다(세션 cron 은 PM 세션이 죽으면 같이 죽으므로 이것은 안 된다).
- 주기: 진행 중엔 30분 간격 정도(작업 단위의 3배). 프로젝트를 닫으면 끈다.
- 재는 것: PM 세션 점검이 실제로 돌았는지(마지막 점검 기록 시각) · 20분 넘게 움직임 없는 가지·카드가 넘겨받기 없이 남았는지 · 끝난 가지가 다음 단계로 안 넘어간 채 남았는지.
- 어긋나면: PM 에게 먼저 알리고, 한 주기 뒤에도 그대로면 팀장에게 알린다. 잡은 PM 이 아닌 쪽(시스템 발신)이 알린다.

## 구조 가드 — 미리 쌓지 말고, 사이드 이펙트가 보이면 나눈다

기준은 줄 수가 아니다. 한 클래스·함수가 일을 여럿 떠안아 하나를 고칠 때 다른 것이 깨지는지가 기준이다. 기능이 적을 때 처음부터 층을 나누지 않는다. 정본은 `b3os-ai-code-safety` Phase 1.
- 주 기준: 여러 구역이 같은 값을 직접 쓰는 수. 늘면 테스트 실패, 목표는 값마다 입구 하나.
- 주 기준: 한 구역을 깨뜨린 뮤턴트가 다른 구역 테스트를 깨뜨리면 그 자리가 나눌 곳.
- 한 상태를 필드 셋 이상의 조합으로 판단하게 되면 상태 하나 + 전이표(`reduce`)로.
- 파일·함수 줄 수는 신호로만 보고한다(실패시키지 않는다).

## 검증 규율

프로젝트 PR 검증은 `b3os-ai-code-safety` 를 따른다 (뮤턴트 · 양쪽 재기 · 화면은 사진에서 · 소스 진단은 재현 전까지 후보). 증명 방법·래칫·검사가 틀렸을 때의 분류·한 번에 도는 러너는 `b3os-verification`. 병합 메시지에는 ★잰 것 · 안 잰 것★ 을 적는다. 틀린 것은 메모리·SHARED.md 로.

## 인계 (다른 팀원에게 넘길 때) — 4줄
지시 요지 · 진행 여부 · 저장소·브랜치 기준점 · 범위. 하나라도 빠지면 받는 쪽이 멈추거나 엉뚱한 데서 일한다. 브랜치 기준점을 안 주면 앞 수정을 조용히 되돌린다.

## 관련
`b3os-task-loop`(카드·대기) · `b3os-slack-format`(슬랙) · `b3os-github-workflow`(저장소 글) · `b3os-how-to-explain`(설명) · `b3os-team-inbox`(버스) · `b3os-ai-code-safety`(검증) · `b3os-harness-playbook`(병렬)