같은 Astrid OS 프로젝트의 자매 문서다. book이 "무엇을 만들었나"(기술 사양)라면, handbook은 "어떻게 함께 만드는가"(운영·거버넌스)다. 폴리레포 구조, "커널은 멍청하다" 법칙, 언제 RFC가 필수인가, 4단계 기여 등급, 릴리스 규율을 — 권고가 아니라 CI로 강제되는 '하드 법(hard law)'으로 못 박았다. 마크다운 6장뿐인데 별이 2.6k다. (저장소: unicity-astrid/handbook · "The Astrid Contributor Handbook" · mdBook · Apache-2.0+MIT · ★ 2.6k · 커널 astrid ★ 9.2k · TrendShift #23)
"오픈소스 OS 하나를 '규율 있게' 굴리는 법을, 코드처럼 박아둔 법전."
오픈소스 프로젝트 대부분의 CONTRIBUTING.md는 "이렇게 해주세요" 정도의 부드러운 권고다. Astrid는 다르다. 거버넌스를 지키지 않으면 빌드가 깨지는 '하드 법'으로 만들었다. 기여 등급이 "당신이 어떤 파일을 건드릴 수 있는지"를 가르고, 계약 표면을 바꾸려면 RFC가 요청이 아니라 필수이며, 버전 올리기는 별도 PR로 격리해야 하고, 모든 PR은 이슈를 닫아야 한다 — 전부 .github/workflows/에 배선돼 있다.
중요한 건 대상 독자다. 서문이 못 박는다 — "이 핸드북은 Astrid로(with) 무언가를 만드는 사람이 아니라, Astrid를(on) 바꾸는 사람을 위한 것". 즉 커널·SDK·계약 표면·레퍼런스 캡슐을 손대는 사람용이지, 캡슐 앱을 만드는 일반 사용자용이 아니다. 그래서 이 문서는 'OS 내부 사양'이 아니라 '그 OS를 함께 짓는 규율'을 다룬다(내부 사양은 자매 문서 book의 몫).
astrid-capsule-<이름>)과 레포 이름(capsule-<이름>)을 매핑하는 규칙까지 정해 둔다.저자는 book과 같은 Joshua J. Bouw(Unicity Labs), 라이선스도 Apache-2.0+MIT다. 분량은 서문 + 5개 챕터(마크다운 6개, 약 1,200줄)로 작지만 밀도가 높다. "문서와 코드가 다르면 코드가 이긴다 — 문서가 버그다"라는 셋째 규칙이 이 작은 책의 태도를 압축한다.
"별 9천짜리 보안 OS를 '어떻게 운영하는지'가, 코드만큼 배울 거리라서."
사람들은 코드만 보지 않는다. 보안이 중요한 프로젝트를 '어떻게' 굴리는지를 궁금해한다. 핸드북은 단 6장의 마크다운으로 별 2.6k를 모았는데, 그 자체가 신호다 — 거버넌스를 '읽을 가치가 있는 문서'로 만든 드문 사례다.
대부분의 기여 가이드는 "커밋 메시지는 이렇게, 테스트는 꼭"이라고 말로만 적는다. 강제력이 없으니 신규 기여자가 보안 핵심 코드를 덜컥 건드리거나, 버전 변경과 기능 변경이 한 PR에 뒤섞여 리뷰가 어려워지거나, 이슈 없는 PR이 쏟아진다. 규율이 '문화'에만 기대면, 사람이 바뀔 때마다 흔들린다.
Astrid는 규율을 자동 강제한다. 기여 등급이 '건드릴 수 있는 파일 경로'를 막고, 계약 표면 변경엔 RFC가 필수이며, 버전 올리기는 별도 PR이어야 하고, 모든 PR은 Closes #N으로 이슈를 닫아야 한다. 1000줄 넘는 파일은 거부되고, 커밋은 GPG 서명이 필수다. 규율이 사람의 의지가 아니라 파이프라인에 박혀 있다.
보통 기여 가이드 = "안전벨트 매주세요" 스티커 — 안 매도 차는 출발한다.
Astrid 핸드북 = 벨트를 안 매면 시동이 안 걸리는 차 — 규칙이 안내문이 아니라 장치다. 그래서 누가 운전석에 앉아도 규율이 유지된다.
게다가 핸드북엔 가르칠 만한 원칙이 많다. 대표가 "커널은 멍청하다(kernel-is-dumb)" 법칙 — 커널은 라우팅·게이팅·검증만 하고 비즈니스 로직은 0이라는 건축적 불변식을, 옳은 예/틀린 예까지 붙여 가르친다. 보안 위협 모델을 컴파일러 린트(arithmetic_side_effects = "deny")에까지 박아 넣은 점, GPG 서명·콘텐츠 주소(BLAKE3) 바이너리·빌드 출처 메트릭 같은 디테일도 흔치 않다.
| 항목 | 보통 OSS | Astrid 핸드북 |
|---|---|---|
| 규율 성격 | 권고(양심) | CI 강제(하드 법) |
| 누가 뭘 건드리나 | 대체로 자유 | 기여 등급별 경로 게이트 |
| 계약 변경 | PR로 바로 | RFC 필수 → 리뷰 → 머지 |
| 버전 올리기 | 아무 PR에나 | 별도 격리 PR |
| 커밋/이슈 | 자유 | GPG 서명 + 이슈 우선(Closes #N) |
여기서 '스택'은 도구가 아니라 '방법론'이다 — 그걸 발행·강제하는 얇은 도구가 곁들여진다.
이 레포의 '기술 스택'은 방법론 스택이다. 다섯 방법론 부품과, 그것을 웹으로 발행하고 CI로 강제하는 도구로 나뉜다.
| 부품 | 무엇인가 |
|---|---|
| 폴리레포 모델 | 커널·SDK·RFC·모든 캡슐이 각각 별도 레포. 로컬에선 한 상위 폴더에 나란히 |
| "커널은 멍청하다" 법칙 | 커널은 라우팅·게이팅·검증만. "라우팅/게이팅/검증 안 하면 그건 캡슐 IPC 영역" |
| RFC 트리거 | 7가지 계약 표면 변경 시 RFC 필수. 내부 변경엔 불필요 |
| 기여 등급 | New → Astrinaut → Core → Maintainer, CI가 경로로 게이팅 |
| 릴리스 프로세스 | 태그(v*) 트리거, 4타깃 빌드, 콘텐츠 주소 바이너리, 격리된 버전 PR |
| 도구 | 역할 |
|---|---|
mdBook 0.5.2 | 핸드북을 정적 사이트로(테마 ayu) → GitHub Pages 자동 배포 |
| Conventional Commits | feat/fix/chore/docs/... 접두사 규약, GPG 서명 필수, HTTPS 푸시 |
커널 CI(pr-checks.yml) | template·contributor-gate·file-size·linked-issue·account-age |
커널 CI(ci.yml) | check·fmt·clippy -D warnings·test·msrv(1.95)·audit |
| Rust 린트 | unsafe_code="deny" · arithmetic_side_effects="deny" · rustfmt 100열 · 파일 1000줄 한도 |
타입: 요약 형식(feat:, fix: …)으로 통일하는 규약으로, 자동 체인지로그·릴리스 노트의 토대가 된다.'아이디어 → RFC 관문 → 이슈 우선 → 자기검열 → CI 게이트 → 머지 → 릴리스'의 파이프라인.
핸드북은 하나의 변경이 아이디어에서 릴리스까지 어떻게 흐르는지를 정의한다. 핵심은 세 개의 독립적 관문 — 코드보다 앞선 RFC 관문, PR 시점의 등급+CI 관문, 분리된 릴리스 관문이다.
이 흐름의 통찰은 관문이 세 번 따로 선다는 것이다. RFC는 코드보다 앞에서(설계), 등급+CI는 PR 시점에서(권한·품질), 릴리스는 격리된 PR과 태그에서(배포) 막는다. 각 관문이 독립적이라, 한 곳을 통과해도 다음에서 다시 걸러진다.
마크다운 6장이 전부 — 서문 + 5개 챕터가 '운영 법전'의 5개 기둥.
레포는 mdBook 한 권이다. src/ 아래 서문 1장 + 챕터 5장(약 1,200줄)이 곧 다섯 기둥 — 폴리레포·커널법칙·RFC·기여등급·릴리스다.
| 챕터 | 핵심 |
|---|---|
| 서문 | 대상('Astrid를 바꾸는 사람') + 세 규칙: ① 커널은 멍청 ② RFC는 계약 변경용 ③ 코드에 근거 |
| 폴리레포·워크플로 | 레포 지도, 디렉터리↔레포 매핑, origin/main 브랜치, GPG 서명, 이슈 우선, 10항 점검표 |
| 커널은 멍청하다 | 커널의 세 임무(라우팅/게이팅/검증), 6개 옳은·틀린 예, 기여자 점검표 |
| RFC 트리거 | 7가지 계약 표면, 7문항 테스트, RFC 9개 섹션, 생애주기(Draft/Active/Final) |
| 기여 등급·보안 크레이트 | 4단계 + CI 게이팅, 보안 핵심 8개 크레이트, 취약점 신고(48h/7d) |
# contribution-tiers — 이 경로들을 건드리면 등급이 막는다
SECURITY_PATHS="crates/astrid-crypto crates/astrid-capabilities \
crates/astrid-audit crates/astrid-approval crates/astrid-vfs \
crates/astrid-storage crates/astrid-sys crates/astrid-core"
CORE_PATHS="crates/astrid-kernel crates/astrid-events \
crates/astrid-hooks crates/astrid-config crates/astrid-mcp"
# Astrinaut가 SECURITY_PATHS/CORE_PATHS를 건드리면 CI가 즉시 실패"코드가 아니라 '엔지니어링 운영'을 배우는" 드문 교본.
레포-당-컴포넌트 구성, 디렉터리↔레포 매핑 규칙, "각 컴포넌트가 별도 레포라 먼저 cd", origin/main에서 브랜치(로컬 main은 낡는다)까지 — 모노레포와의 트레이드오프(스코프 규율, 크로스레포 브랜치 불가)가 명시돼 있다.
핵심 통찰은 '계약 표면'만 게이팅하고 내부는 자유롭게 둔다는 것. "게스트에게 보이는 WIT가 바뀌나? 캡슐을 재컴파일해야 하나?"라는 리트머스가 그대로 재사용 가능한 휴리스틱이다.
가상의 새 호스트 함수에 대해 RFC 9개 섹션(요약·동기·가이드·레퍼런스·단점·대안·선행연구·미해결·향후)을 채워 한 편 써 보라. 시그니처와 에러 계약까지 명시해야 진짜다.
신뢰를 문서가 아니라 CI 경로 게이트로 인코딩하는 법. 신규는 라벨 필요, 하위 등급이 보안 경로를 건드리면 하드 실패, 코어가 암호 경로를 건드리면 소프트 경고 — 단계적·자동화 가능한 모델이다.
나만의 contributors.yml + contributor-gate 셸 스니펫을 작성해, PR 작성자의 등급을 분류하고 SECURITY_PATHS를 건드린 하위 등급을 하드 실패시켜 보라.
버전 올리기를 별도 PR로 격리(리뷰어가 진짜 변경만 보게), 태그 트리거 릴리스, 무결성용 콘텐츠 주소(BLAKE3) 바이너리. 그리고 "커널은 멍청하다"처럼 불변식을 선언하고 옳은/틀린 예 + 기여자 점검표로 박아 원칙이 실제 PR에서 살아남게 하는 법.
자기검열("새벽 3시"), 5가지 위협 모델 질문, 안전한 실패(fail-secure)를 비협상 원칙으로 두기, 위협 모델을 컴파일러 린트에 박기(arithmetic_side_effects="deny", std::env::set_var 금지) — 보안을 '문화'가 아니라 '장치'로 만드는 실전.
핸드북 자체는 마크다운. 다만 '기여'하려면 Rust·GPG·이슈·등급 조건을 갖춰야 한다.
핸드북을 읽고 빌드하는 데엔 mdBook 하나면 된다. 진짜 '요구사항'은 Astrid에 기여하기 위한 전제 조건들로, 핸드북이 깐깐하게 명시한다.
| 목적 | 요구 | 비고 |
|---|---|---|
| 핸드북 읽기 | 웹브라우저 | unicity-astrid.github.io/handbook |
| 로컬 빌드 | mdbook serve --open | mdBook(CI 0.5.2 고정), 순수 마크다운 |
| Rust 툴체인 | 커널 1.95 · SDK 1.94 · Edition 2024 | 캡슐은 wasm32-unknown-unknown 타깃 |
| 커밋 | GPG 서명 필수 | git log --format="%G?"가 G여야 |
| 계정 | 30일 이상 권장 | account-age 잡이 신규 계정에 경고 |
| PR 전 | 이슈 먼저 | 무단 PR은 닫힘(이슈 우선 규칙) |
| 제출 전 점검 | fmt · clippy -D warnings · test | CI와 동일 기준 |
좋은 의도로 큰 PR을 던져도, 이슈가 없으면(Closes #N 누락) linked-issue가, GPG 서명이 없으면 검증이, 파일이 1000줄을 넘으면 file-size가, 등급보다 민감한 경로를 건드리면 contributor-gate가 막는다. "코드가 좋으면 통과"가 아니라 "절차를 지켜야 통과"다. 그래서 핸드북을 먼저 읽으라는 것.
"세 규칙 요약 → 로컬 빌드 → RFC 작성 → 등급 게이트 구현 → 트리거 봇"으로 난이도 상승.
서문을 읽고 ① 커널은 멍청 ② RFC는 계약 변경 ③ 코드에 근거 — 세 규칙을 각각 한 줄로 자기 말로 정리한다. 왜 이 셋이 '모든 걸 지배'하는지 생각해 본다.
cargo install mdbook → 클론 → mdbook serve --open. 챕터를 하나 추가해 SUMMARY.md에 연결하고, GitHub Pages 배포 워크플로(deploy.yml)를 재현해 본다.
가상의 새 호스트 함수(예: astrid:clock)에 대해 RFC 9개 섹션을 채운다. "이 변경이 7개 계약 표면 중 무엇을 건드리나"를 트리거 체크리스트로 먼저 판정하는 게 핵심.
contributors.yml과 contributor-gate 셸 스크립트를 직접 짜서, PR 작성자 등급을 분류하고 SECURITY_PATHS를 건드린 하위 등급 PR을 하드 실패시킨다. GitHub Actions로 돌려 본다.
PR diff를 스캔해 wit/host/·wit/interfaces/·매니페스트 스키마 변경을 감지하면 "RFC required"를 자동 코멘트하는 봇을 만든다. 또 "버전 줄과 .rs 변경이 한 PR에 섞이면 실패"시키는 체크도 추가.
'OSS 거버넌스 → RFC 프로세스 → 기여등급·CI → 릴리스·보안 리뷰'의 4주 코스.
| 주차 | 주제 | 학습 내용 & 핸드북 연결 |
|---|---|---|
| 1주차 | OSS 거버넌스 기초 | 모노레포 vs 폴리레포, Conventional Commits, GPG 서명. polyrepo-and-workflow.md로 레포 지도와 깃 규약을 학습. |
| 2주차 | RFC 프로세스 설계 | RFC 생애주기, '계약 표면'만 게이팅하는 휴리스틱. rfc-trigger.md 정독 후 RFC 한 편 작성. |
| 3주차 | 기여 등급 & CI 게이팅 | 경로 기반 권한, 보안 핵심 크레이트, PR CI 잡 5종. contribution-tiers.md로 게이트 로직을 분해해 재구현. |
| 4주차 | 릴리스 규율 & 보안 리뷰 | 격리된 버전 PR, 콘텐츠 주소 바이너리, 자기검열·위협 모델. release-and-standards.md로 린트·릴리스 파이프라인을 통독. |
이 핸드북은 운영·거버넌스를 다루고, 자매 문서 book은 커널·캡슐·ABI·버스·보안의 기술 사양을 다룬다. "왜 이런 규율이 필요한가"는 handbook이, "그 규율이 지키려는 구조가 무엇인가"는 book이 답한다. 둘을 짝지어 읽으면 "보안 OS를 어떻게 설계하고 어떻게 함께 짓는가"가 입체적으로 잡힌다. (같은 폴더 astrid-book-deep-dive.html 참고)
핸드북에 반복되는 운영 용어를 한 곳에.
astrid-capsule-<이름>)와 레포(capsule-<이름>)를 매핑한다.rfcs 레포, 머지 때 번호 부여, Draft→Active→Final). 트리거는 7가지 계약 표면 중 하나라도 바뀌면 RFC가 필수임을 판정하는 규칙. 리트머스: "게스트가 보는 WIT 표면이 바뀌나?"contributors.yml 정의, contributor-gate 잡 강제).astrid-crypto·astrid-capabilities·astrid-audit·astrid-approval·astrid-vfs·astrid-storage·astrid-sys·astrid-core). Core/Maintainer만 수정 가능.Closes #N으로 닫아야 한다는 규칙. linked-issue 잡이 강제하며, 이슈 없는 무단 PR은 닫힌다.~/.astrid/bin/<해시>.wasm)에 저장하는 방식. 무결성·동시성 안전을 위해 임시 파일 후 원자적 rename으로 쓴다.공식 저장소·호스팅판·자매 레포.
GitHub 저장소(handbook) · github.com/unicity-astrid/handbook — "The Astrid Contributor Handbook" 원본.
호스팅판(읽기) · unicity-astrid.github.io/handbook — 설치 없이 바로 읽기.
자매 문서(book) · github.com/unicity-astrid/book — 기술 사양(같은 폴더 astrid-book-deep-dive.html 참고).
RFC 저장소 · github.com/unicity-astrid/rfcs — RFC 템플릿·제안 목록.
커널 저장소 · github.com/unicity-astrid/astrid — CI 워크플로·크레이트가 사는 곳(★ 9.2k).
조직/제작 · unicity.ai (Unicity Labs)
TrendShift · trendshift.io/repositories/60290