b3os-github-workflow

GitHub 워크플로 — 변경을 PR로 올려 머지까지

코드·주석·커밋·PR·문서는 인과관계와 사실로 쓴다. 회고와 사람의 발언은 저장소 밖에서 다룬다. 간결하게, 짧은 문장으로.

b3os 인프라(소스·config·registry·릴리스)를 고치면 b3os-infra-safety 를 먼저 보고 이 절차를 얹는다.

무엇을 쓰나 — 저장소에 남는 글은 사실과 인과만

저장소에 들어가는 것은 전부 공개물이다. 용도가 정해져 있다.

어디	무엇을
README·가이드	하는 방법 + 확인 방법
PR 본문	무엇이 문제인가(사실) → 왜 그렇게 되나(인과) → 어떻게 고쳤나 → 검증 결과
커밋 메시지	무엇을 바꿨고 왜 그게 맞는가
코드 주석	이 코드가 무엇을 하는가, 왜 이 조건이 필요한가
메모리·SHARED.md	회고·리뷰는 전부 여기. 밖에 안 나간다

빼는 것은 회고성 서술이다 — 사고 경위, "오늘 우리가", 작업 과정의 날짜, 그 일에 관계없는 사람 이름.

이 규칙은 PR·문서만이 아니라 코드와 주석에도 적용된다. 저장소에 남거나 밖으로 나가는 글 전부가 대상이다 — 코드, 주석, 커밋 메시지, PR, 이슈, 외부 문서.

빼는 것 셋

① 팀 대화 인용. 팀장·팀원이 무슨 말을 했는지는 저장소에 남기지 않는다. 변경의 근거는 요구사항이나 측정값으로 적는다. 누가 요청했는지는 근거가 아니다 — 그게 근거라면 다음 사람은 그 말을 찾을 수 없어 판단을 재현하지 못한다.

대상은 팀 내부 대화다. 외부 출처는 인용한다 — 업스트림 이슈, 벤더 문서, 표준 문서의 문장이 우회 코드의 유일한 근거인 경우가 있다. 그건 링크와 함께 남긴다. 다음 사람이 실제로 찾아가 확인할 수 있기 때문이다.

② 자기비판·반성. "내가 놓쳤다", "이걸 몰라서 밟았다" 는 저장소 밖으로 간다. 남길 값은 후회가 아니라 무엇이 참인가다.

③ 사람에게 귀속된 리뷰 이력. "누구 리뷰에서 나왔다" 대신 무엇이 관측됐는지를 적는다.

이렇게 바꾼다

쓰지 않는다	대신
팀장님 지시 2026-07-30	요구사항:
GD 결정 · 팀 리드 결정	제품 결정:
팀장님 실측 · bill 지적	실측: · 리뷰 지적:
codex 리뷰에서 나온 · dbak 지적	리뷰에서 관측된
오늘 4건이 조용히 사라졌다	이 경로에서 4건이 통보 없이 유실된다
내가 세 번째까지는 요청했다	(삭제)

남기는 것: 관측값, 재현 조건, 인과, 검증 방법, 그리고 그 판단이 왜 맞는가.

절차가 요구하는 신원은 그대로 쓴다 — 커밋 author, Co-authored-by 를 비롯한 git trailer, PR 본문의 Submitted-by, 리뷰 승인 계정, 코드에서 참조하는 버전·날짜. 이건 인용이 아니라 추적에 필요한 사실이다.

★그중 일부는 기계가 읽는 값이다.★ Approved-by: <이름> 은 산문이 아니라 머지 게이트가 merge_approvers_normal 과 대조하는 입력이다(skills/b3os-release-ops/scripts/release-preflight.sh). 이 규칙을 "사람 이름을 빼라" 로 읽고 지우면 게이트가 깨진다.

왜 이게 규칙인가

저장소는 공개물이고, 개인 이름·역할·대화는 코드와 함께 영구히 나간다. 그리고 회고성 서술은 다음 사람에게 쓸모가 없다 — 그가 필요한 것은 "누가 언제 무엇을 말했다" 가 아니라 "지금 이 조건이 왜 이래야 하는가" 다.

회고·리뷰·교훈은 메모리와 SHARED.md 로 간다. 없애는 게 아니라 자리를 옮기는 것이다.

설정에서 읽을 값

아래 값은 이 문서에 적지 않는다. 환경마다 다르고, 문서에 박히면 그 자체가 공격 지점 안내가 된다.