task-flow

좌표

항목	값
노션 DB	업무 관리 / 작업 관리 — collection://f3d9059c-1010-46c8-a8ce-5f7656ab3ecc
내 노션 user id	3cdd872b-594c-81fe-b8f8-00022b0f4102
백볼트(위키)	레포와 같은 부모 디렉터리의 backend-llm-wiki. 규칙은 그 레포의 REPO-CLAUDE.md
분기 기준	항상 origin/develop (main/master 아님)
브랜치	기능은 feature/{kebab-case}, 수정은 fix/{kebab-case}
MR 타겟	develop
제목	Conventional Commits — feat(scope): 제목, fix(scope): 제목
본문	같은 디렉토리의 template.md
구현 위임	cosmos 커맨드 (spec→dev→qe→로컬 커밋). 로컬 커밋까지만 하고 push·MR 은 안 한다

type은 feat fix refactor perf test docs chore 중 하나.
브랜치 prefix와 제목 type은 맞춘다 (fix/ 브랜치면 제목도 fix:).

레포가 여러 개로 갈리는 작업(예: processor/mavlink + processor/dji)은
브랜치명을 똑같이 쓰고 MR 끼리 서로를 「짝 MR」로 링크한다. 노션 작업은 하나만 만든다.

전체 흐름

0 노션 티켓 → 1 위키 조회 → 2 전제 → 3 브랜치 → 4 구현(cosmos|직접)
  → 5 커밋 ⏸ → 6 push → 7 MR 본문 → 8 MR 생성 ⏸ → 9 코드리뷰 → 10 위키 ingest ⏸
  → 11 노션 마무리 → 12 옵시디언 진입점

⏸ 는 사용자 승인 없이 넘어가지 않는 지점이다.

중간부터 들어와도 된다. "MR만 올려줘"처럼 특정 단계를 지목하면 그 단계부터 한다.
다만 0·10·11 은 건너뛰지 말고 한 줄로 확인한다 — 이 셋이 빠뜨리기 쉬운 자리다.
("노션 티켓 있나요?" / "위키에 남길 게 있나요?" 정도면 된다.)

절차

0. 노션 — 티켓을 만들지부터 정한다

먼저 이미 있는지 본다.

mcp__notion__notion-query-data-sources  mode: sql
  SELECT "작업 이름", "상태", "유형", url
  FROM "collection://f3d9059c-1010-46c8-a8ce-5f7656ab3ecc"
  ORDER BY createdTime DESC LIMIT 30

제목이 안 겹쳐도 같은 일일 수 있다. 최근 30건을 훑어서 내용으로 판단한다.

• 있으면 — url 을 들고 간다. 상태가 시작 전이면 진행 중으로 올린다.
• 없으면 — 아래 기준으로 만들지 정한다.

만든다	만들지 않는다
MR 이 나가는 작업 — 팀에 보이고 리뷰가 붙는 것	로컬 환경·dotfiles·에디터 설정
사용자가 "작업"으로 지시한 것	조사·질문에 답하기만 하고 끝나는 것
여러 세션에 걸칠 만한 것	곁가지로 튀어나온 즉흥 수정

애매하면 만드는 쪽이 아니라 묻는 쪽이다. 만들기 전에 한 줄로 확인받는다.

mcp__notion__notion-create-pages
  parent: { data_source_id: "f3d9059c-1010-46c8-a8ce-5f7656ab3ecc" }
  properties:
    작업 이름: "<작업 이름>"
    상태: "진행 중"                    # 시작 전 / 진행 중 / 완료 / 보류
    유형: "개선"                       # 필수 / 개선 — 최상위 작업에만
    담당자: ["3cdd872b-594c-81fe-b8f8-00022b0f4102"]
    시작일: "<오늘>"

본문 양식은 notion-ticket 스킬이 갖고 있다 — 「🎯 무엇을」 + 「📐 계약」 두 블록이고,
진행 중에만 의미 있는 것(MR·체크리스트·실측)은 하위 페이지로 내린다. 티켓을 만들거나 본문을
정리할 때 그 스킬을 부른다. 계약이 아직 없으면 「🎯 무엇을」만 쓰고 비워 둔다.

상위 작업·프로젝트 릴레이션이 걸릴 자리가 보이면 걸어둔다. 나중에 추적이 된다.

1. 위키 조회 — Query-before-code

백볼트 REPO-CLAUDE.md 의 규칙이다. 설계 판단이 필요한 작업이면 코드를 만지기 전에 읽는다.

• 새 기능, 구조 변경, 다른 서비스와의 연계, 원인 불명 버그 → 읽는다
• 오타·한 줄 픽스·설정 손질 → 생략

읽는 순서: ../backend-llm-wiki/wiki/index.md 에서 관련 페이지를 찾고,
decisions/(왜 이렇게 했는가) → guides/(절차·함정) → 해당 서비스 허브.
백볼트에 wiki-query 스킬이 있으면 그걸 쓴다.

여기서 읽은 내용은 7번 MR 본문의 "왜"에 그대로 쓰인다. ADR 번호를 기억해 둔다.
위키와 실제 코드가 모순되면 그 자리에서 고치지 말고 10번에 ⚠ 충돌 로 넘긴다.

2. 전제 확인

git remote -v                      # origin이 gitlab인지
glab auth status                   # 로그인돼 있는지
git fetch origin develop

glab이 없거나 로그인이 안 돼 있으면 거기서 멈추고 사용자에게 알린다.
직접 glab auth login을 돌리지 않는다.

3. 브랜치

현재 브랜치가 이미 feature/* 또는 fix/*면 그대로 쓴다.
아니면 origin/develop에서 새로 딴다:

git checkout -b feature/tlog-minio-sink origin/develop

이름은 작업 내용에서 뽑되 짧게(2~4단어). 이슈 키를 사용자가 주면 feature/PROC-142-minio-sink처럼 앞에 붙인다.

4번에서 cosmos 에 맡길 거라면 여기서 브랜치를 만들지 말고 이름만 정한다 — cosmos 가
워크트리를 만들면서 그 브랜치를 함께 만든다. 두 번 만들면 충돌한다.

4. 구현 — cosmos 에 맡길지 정한다

cosmos 에 맡긴다	직접 한다
spec 을 쓸 만한 규모 — 파일 여러 개	한두 파일, 한 줄 수정
Acceptance Criteria 를 문장으로 쓸 수 있다	"고쳤는지"가 눈으로 보이면 끝
테스트·타입체크로 자동 검증된다	설정·문서·환경 손질

사용자가 방식을 지정했으면 그대로 따른다. 애매하면 묻는다.

cosmos 에 맡길 때 — cosmos 커맨드를 호출하고 브랜치와 base 를 명시해서 넘긴다.

/cosmos <요청 또는 spec 경로>
  브랜치: feature/tlog-minio-sink
  base:   origin/develop

cosmos 는 <repo>/.claude/worktrees/<slug> 에 워크트리를 만들고 거기서 돈다.
로컬 커밋까지만 하고 멈춘다 — push·MR·노션·위키는 여기(task-flow)의 일이다.

돌아오면 결과를 확인한다:

• committed — 커밋 sha·브랜치·워크트리 경로를 받는다. 5번을 건너뛰고 6번으로.
  이후 git 명령은 그 워크트리에서 실행한다. 원본 트리에는 변경이 없다.
• loop_exhausted / aborted — 구현이 안 끝난 것이다. push·MR 로 넘어가지 않는다.
  실패 요약을 사용자에게 전하고 다음 판단을 받는다 (spec 손보기 / 직접 구현 전환 / 중단).
• ops.sha 가 BLOCKED_NO_COMMIT_CREATED 면 committed 여도 커밋이 없다. cosmos 커맨드의
  안내대로 원본 트리에서 재검증 후 커밋한다.

워크트리 정리(git worktree remove)는 MR 이 머지된 뒤 사용자가 직접 한다. 임의로 지우지 않는다.

직접 할 때 — 그냥 구현하고 5번으로 간다.

5. 커밋 — 여기서 한 번 멈춘다

cosmos 경로면 이미 커밋돼 있다. 이 단계를 건너뛰고 6번으로 간다.

git-commit 스킬로 넘긴다. 스테이징·커밋 단위·제목/본문·트레일러·스쿼시는 전부 그쪽이 갖고 있다.
넘길 때 분기 기준 origin/develop 을 인자로 준다 — 그 값은 이 스킬 소유다.

승인 게이트(⏸)는 그대로다. 스테이징할 파일 목록과 커밋 메시지를 보여주고 승인받기 전에는 커밋하지 않는다.

6. push

git push -u origin <branch>

cosmos 경로면 워크트리 안에서 실행한다. 원본 트리에서 치면 그 브랜치가 없다.

7. MR 본문 작성

template.md를 읽고 아래로 채운다. 빈 섹션을 그대로 두지 않는다.

• 무엇을 / 왜 — 커밋 메시지를 반복하지 않는다. diff에 안 드러나는 배경과 판단 근거.
  1번에서 읽은 ADR·가이드가 여기 근거로 들어간다. 모르면 지어내지 말고 사용자에게 묻는다.
• 변경 사항 — git diff origin/develop...HEAD --stat을 근거로. 파일 나열이 아니라
  "무엇이 달라졌나" 단위로.
• 확인 방법 — 리뷰어가 따라할 수 있는 명령/절차. 없으면 N/A.
  cosmos 경로면 spec 의 Acceptance Criteria 가 그대로 근거가 된다.
• 설계 정본(옵시디언 노트)이나 짝 MR 이 있으면 링크 줄로 남긴다.
• 안내용 HTML 주석(<!-- ... -->)은 최종 본문에서 지운다. 스크린샷 자리 주석만 남길 수 있다.
• 🤖 Generated with [Claude Code]·세션 URL 을 본문 끝에 붙이지 않는다. 도구 기본값이라 매번 뺀다.

8. MR 생성 — 여기서 또 한 번 멈춘다

제목 / 타겟 브랜치 / Draft 여부 / 본문 전문을 보여주고 승인을 받는다.
승인 후에만:

glab mr create \
  --target-branch develop \
  --title "feat(tlog): MinIO sink 백프레셔 추가" \
  --description "$(cat /tmp/mr-body.md)" \
  --yes

• 아직 리뷰받을 단계가 아니면 --draft를 붙인다
• 성공하면 반환된 MR URL을 사용자에게 그대로 준다

이미 MR이 있으면 glab mr list --source-branch <branch>로 확인하고,
새로 만들지 말고 glab mr update <id> --description "$(cat ...)"로 본문만 갱신한다.

9. 코드리뷰

MR 을 올린 뒤 code-review 스킬로 스스로 한 번 훑는다. 사람 리뷰어를 대신하는 게 아니라,
리뷰어가 지적할 게 뻔한 것을 먼저 걷어내려는 것이다.

• 기본은 현재 브랜치 diff 를 본다
• 나온 지적은 고칠 것 / 의도된 것 / 별건으로 나눈다. 전부 고치려 들지 않는다
• 고쳤으면 5~6번으로 돌아가 커밋·push 한다. MR 본문의 "변경 사항"도 같이 갱신한다
• 의도된 선택이라 안 고치는 건 MR 본문이나 코멘트에 이유를 남긴다 — 리뷰어가 같은 걸 또 짚는다

사용자가 이미 리뷰를 돌렸거나 급하면 건너뛴다. 다만 건너뛴다고 말은 한다.

10. 위키 ingest — 제안까지만 한다

백볼트 REPO-CLAUDE.md 의 Ingest-after-work 다.
코딩 세션에서 위키를 자동 수정하지 않는다. 무엇을 남길지 정리해서 사용자에게 제안하고,
승인하면 백볼트의 wiki-ingest 스킬로 넘긴다.

남길 가치가 있는 것:

• 설계 결정과 그 근거 — 특히 채택하지 않은 안과 그 이유
• 함정 — 다음 사람이 같은 데서 막힐 것
• 컨벤션, 다른 서비스와의 발산 지점
• 1번에서 발견한 위키와 코드의 모순 → 해당 페이지에 ⚠ 충돌 블록 제안

남길 게 없으면 없다고 말하고 넘어간다. 오타 수정에 ingest 를 붙이지 않는다.

기록 자리는 보통 두 곳이다 — wiki/log.md 상단에 항목 하나,
그리고 영향받은 decisions/·services/ 페이지. MR 번호를 함께 적어야 나중에 되짚을 수 있다.

11. 노션 마무리

MR 링크는 **본문이 아니라 하위 페이지 「작업 메모 — MR·배포·검증」**에 붙인다 (notion-ticket 의 층 규칙).
없으면 그때 만든다.

## MR
- [processor/mavlink!1](https://gitlab.com/.../merge_requests/1)
- [processor/dji!1](https://gitlab.com/.../merge_requests/1)

머지까지 확인되면 상태 = 완료, 완료일 = 그날. 머지 전에 완료로 올리지 않는다.

0번에서 티켓을 안 만들기로 했으면 이 단계도 없다.

12. 옵시디언 — 태스크 폴더와 진입점

작업 하나 = 볼트 폴더 하나다. 폴더 스펙과 frontmatter 골격은 같은 디렉토리의 vault-task.md.

~/Documents/para/Project/모빌리티원/태스크/{작업 이름}/
  {작업 이름}.md   설계 정본 — 왜          (필수)
  진입점.md        어디 — 레포·파일 트리    (필수)
  의사결정.md      뒤집은 것과 근거         (있으면)
  검증 기록.md     실물로 확인한 것         (있으면)

이름 넷은 고정이다. 그 외(spec·다이어그램·리뷰 대응·실측)는 작업마다 자유.

공용 문서는 폴더로 들여오지 않는다. 컨벤션 · 설계 원칙 (ADR) · 코드 읽기 로드맵 ·
백볼트 위키는 여러 작업이 공유하고 계속 갱신된다 — 복사본은 다음 작업에서 낡는다.
1단계에서 읽은 것은 frontmatter 참고: 에 링크로 남긴다.

진입점.md 가 이 단계의 산출물이다. 다음에 이 작업을 다시 잡을 때 처음 여는 파일이고,
태스크/태스크 지도.base 의 「진입점」 칼럼에서 바로 열린다.

진입점.md 양식

맨 위에 브랜치와 기간 한 줄, 그다음 레포별 트리. 표가 아니라 트리다.

com.m1insight/www                          ← 본체
├── src/
│   ├── lib/server/data/log/
│   │   ├── index.js            ★신규  buildSessionLog 오케스트레이션 · 413 게이트
│   │   ├── bounds.js           ★신규  :18 DEV_RE · :23 PROD_RE
│   │   └── merge.js            ★신규  :7 collect — 인덱스 순열만 정렬
│   └── components/ActionBar.js         로그 버튼 · 파일명 조립
└── tests/log/{bounds,records,merge}.test.js

• ★신규 로 새 파일과 기존 파일 수정을 가른다
• 같은 자리 여러 파일은 {a,b,c}.test.js 로 접는다 — 트리가 테스트로 뒤덮이지 않게
• 줄 번호는 열어서 확인한 것만. 틀린 좌표는 없는 것보다 나쁘다
• 브랜치에 섞인 곁가지(그 작업과 무관한 커밋)는 트리 밖에 한 줄로 빼둔다
• 트리만 봐선 안 보이는 것 한 줄을 맨 아래에 (「Prefix 는 스트림 생성 시 굳는다」)

파일 목록은 git 에서 뽑는다

기억으로 쓰지 않는다. 브랜치가 작업별로 갈려 있으면 그게 가장 정확하다.

git -C <repo> diff --name-only $(git merge-base develop <branch>) <branch>
# 이미 머지돼 비면 날짜로
git -C <repo> log --all --since=2026-09-02 --until=2026-09-05 --name-only --pretty=format: | sort -u

frontmatter — base 가 이걸 읽는다

태스크 노트(폴더 안 본 노트)에만 넣는다. 하위 노트에는 task 태그를 붙이지 않는다 —
붙이면 태스크 지도.base 에 같이 딸려 온다.

tags: [m1ucs, task, ...]
주제: <한 줄>
단계: 완료          # 완료 / 진행 / 백로그
레포:
  - com.m1insight/www
  - com.m1ucs/processor/mavlink
진입점: "[[{작업 이름}/진입점|진입점]]"
참고:
  - "[[설계 원칙 (ADR)|ADR-005]] — 무엇을 정한 조항인지"
  - "[[선행 태스크]] — 왜 선행인지"

같은 이름의 노트가 폴더마다 생기므로(의사결정.md 둘) 링크는 경로로 건다 —
[[TLog, File 저장 경로 변경/의사결정|의사결정]].

노션 본문의 「코드 좌표」는 여기서 요약해 옮긴다 — 볼트가 정본이다.

하지 않는 것

• develop·main·master에 직접 커밋하거나 push
• 승인 없이 커밋 / 승인 없이 MR 생성 / 승인 없이 노션 작업 생성 / 승인 없이 위키 수정
• force push (사용자가 명시적으로 요청하면 그때만)
• MR 머지 — 머지는 사람이 한다
• 이미 push 된 브랜치의 히스토리 다시 쓰기 (트레일러 정리는 git-commit 스킬의 절차를 따른다)
• 노션 작업을 중복 생성 — 0단계에서 반드시 먼저 찾아본다
• cosmos 워크트리를 임의로 지우기 — 머지 확인 후 사용자가 한다
• cosmos 가 실패(loop_exhausted/aborted)했는데 push·MR 로 넘어가기
• 진입점.md 의 좌표를 기억으로 쓰기 — git 과 실제 파일로 확인한 것만 적는다