가이드

팀에서 사용하는 Rasen

다른 가이드에서 설명한 내용은 혼자 작업하든 20명 팀으로 작업하든 동일하게 적용됩니다. 팀에서 달라지는 것은 주변부의 질문들입니다: 스펙은 어디에 두는지, 팀원들은 계획을 어떻게 리뷰하는지, 이미 사용 중인 풀 리퀘스트 흐름과는 어떻게 맞물리는지.

짧게 답하면: 변경(change)은 그냥 파일일 뿐이고, Rasen은 git을 건드리지 않습니다. 그래서 기존 워크플로우를 대체하는 대신 그 안에 맞아 들어갑니다. 이 페이지는 잘 작동하는 관례들을 정리합니다.

하나의 원칙: Rasen은 git을 건드리지 않습니다

Rasen은 rasen/ 아래에 일반 마크다운을 읽고 씁니다. 프로젝트에서 커밋, 브랜치 생성, 푸시, 풀을 직접 수행하지 않으며, store를 알아서 클론하거나 동기화하지도 않습니다. 즉:

rasen/도 다른 소스 코드처럼 커밋합니다. 스펙, 진행 중인 변경, 아카이브는 프로젝트 이력의 일부입니다. (네, 폴더 전체를 커밋하는 게 맞습니다 — FAQ 참고.)
변경은 코드처럼 버전 관리하는 폴더입니다. rasen/changes/add-dark-mode/는 브랜치 위에 있는 그냥 파일들입니다.
아래 내용은 전부 관례일 뿐 강제 사항이 아닙니다. Rasen이 이렇게 하도록 강제하는 건 아니지만, 자연스럽게 잘 맞습니다.

일상적인 루프

잘 작동하는 워크플로우는 하나의 변경을 하나의 브랜치와 풀 리퀘스트에 대응시킵니다:

git switch -c add-dark-mode        start a branch, as usual
   │
/rasen:propose add-dark-mode        draft the plan (proposal + specs + tasks)
   │
REVIEW THE PLAN                    you read it before any code — see Reviewing a Change
   │
/rasen:apply                        build it; artifacts + code change together
   │
git commit && open a PR            the PR contains the spec delta AND the code
   │
teammate reviews, merges
   │
/rasen:archive                      fold the delta into specs/, move the change to archive/

계획과 코드가 같은 브랜치 안에 나란히 존재하기 때문에 팀원들은 둘을 함께 리뷰하게 되고, 6개월 뒤 아카이브된 스펙을 보면 그 코드가 왜 지금 이런 모습인지 여전히 설명이 됩니다.

풀 리퀘스트에서 스펙 리뷰하기

팀이 진짜 이득을 보는 지점이 바로 여기입니다. PR에 변경의 델타 스펙이 포함되어 있으면, 리뷰어는 원시 diff만으로는 절대 얻을 수 없는 것을 얻게 됩니다: 코드를 단 한 줄도 읽기 전에 이 변경이 무엇을 해야 하는지에 대한 평이한 언어로 된 설명입니다.

리뷰어에게 권하는 좋은 리뷰 순서:

proposal.md부터 읽는다 — 이게 맞는 문제이고 맞는 범위인가?
specs/ 아래의 델타를 읽는다 — "완료"가 제대로 정의되어 있는가? (Reviewing a Change에서 설명하는 2분짜리 검토 과정이 이제는 PR 안에서 일어나는 것뿐입니다.)
그다음에 코드 diff를 읽는다 — 그 요구사항을 정확히 구현하고 있는가?

접근 방식 자체에 동의하지 않는 리뷰어는 300줄짜리 코드를 놓고 다시 논쟁하는 대신, 제안서를 상대로 저렴하게 의견을 낼 수 있습니다. 델타 스펙을 PR 설명 상단 근처에 배치하거나, 리뷰어에게 변경 폴더를 알려줘서 거기서부터 보게 하세요.

언제 아카이브할지

아카이브는 변경의 델타를 메인 rasen/specs/에 접어 넣고, 변경 폴더를 rasen/changes/archive/YYYY-MM-DD-<name>/로 옮기는 작업입니다. specs/는 공유된 단일 정보 출처이기 때문에, 팀에서는 타이밍이 중요합니다. 실무에서 쓸 만한 두 가지 관례:

PR이 머지된 후 아카이브한다(권장). 진행 중인 변경은 브랜치에 실려 있다가, 메인 브랜치에 머지되면 그때 아카이브합니다(보통 작은 후속 커밋이나 정기적인 정리 작업으로). 이렇게 하면 공유 specs/는 실제로 배포된 작업만 반영하며 앞으로 나아갑니다.
PR 안에서 아카이브한다. 작은 팀에서는 더 단순합니다: 코드를 추가하는 바로 그 PR이 동기화와 아카이브까지 함께 처리합니다. 다만 specs/ diff와 코드 diff가 한꺼번에 나타나기 때문에 PR이 더 복잡해 보일 수 있다는 게 트레이드오프입니다.

둘 중 하나를 골라서 일관되게 유지하세요. 어느 쪽이든 /rasen:archive는 작업이 완료됐는지 확인하고 먼저 동기화를 제안하므로, 실수로 절반만 끝난 상태로 머지되는 일은 없습니다.

두 사람이 동시에 다른 변경을 작업할 때

변경은 각각 독립된 폴더이기 때문에 서로 충돌하지 않습니다:

다른 변경, 다른 사람 — 문제없습니다. add-dark-mode와 rate-limit-login은 서로 다른 브랜치에 있는 서로 다른 폴더입니다; 둘 다 아카이브되기 전까지는 서로 건드릴 일이 없습니다.
하나의 변경에는 한 명의 소유자만. 두 사람이 같은 변경 폴더를 동시에 편집하면 같은 파일을 두 사람이 동시에 편집하는 것과 똑같이 충돌합니다. 변경은 한 명의 작성자가 담당하도록 유지하거나, 두 개의 변경으로 나누세요(right-size해야 하는 또 다른 이유입니다).
충돌이 나타나는 유일한 지점은 specs/입니다. 두 변경이 같은 요구사항을 수정하면, 두 번째 변경을 아카이브할 때 rasen/specs/…/spec.md에서 충돌이 납니다 — 다른 머지 충돌과 똑같이 해결하면서, 현실을 반영하는 쪽의 요구사항을 남기세요. 이런 일은 드물고, 오히려 유용한 신호입니다: 두 변경이 시스템의 동작 방식에 대해 서로 다른 결론을 냈다는 걸 git이 알려주는 것입니다.

계획이 하나의 저장소를 넘어설 때

지금까지의 내용은 모두 계획이 코드 저장소 자체의 rasen/ 폴더 안에 있다는 전제를 깔고 있으며, 이게 올바른 기본값입니다. 계획이 정말로 여러 저장소나 여러 팀에 걸쳐 있을 때 — 하나의 기능이 세 개의 서비스를 건드리거나, 한 팀이 소유한 요구사항을 다른 팀들이 사용하는 경우 — 그럴 때 쓰라고 있는 게 베타 store 기능입니다: 계획이 자체 저장소를 갖고, 어떤 코드 저장소든 그곳을 가리킬 수 있게 됩니다. Stores User Guide에서 시작하세요.

다음으로 볼 것

Reviewing a Change — 이제는 PR 안에서 이루어지는 리뷰 과정.
Writing Good Specs — 변경을 하나의 브랜치에 맞게 적절한 크기로 나누는 방법 포함.
Stores User Guide — 저장소와 팀을 아우르는 계획 관리.