`/develop` 사이클 (수정중)

1. /develop 이란 — 세 가지를 한 흐름에

/develop 은 "기능 하나를 만들어 합치기(머지)까지" 가는 표준 개발 워크플로우 스킬이다.

여기서 머지란 따로 짠 코드를 원래 코드에 하나로 합치는 것이다. 호출 형식:

/develop [--inplace] [--no-parallel] {app_name} {task_description}

세 가지를 한 흐름에 통합한다 (.claude/skills/develop/SKILL.md):

1. 세션 내 병렬화 — 독립적인 서브에이전트(Agent) 여럿을 동시에 띄운다(탐색·검증·문서). 서브에이전트는 Claude Code 안에서 한 가지 일만 맡아 자기 창에서 처리하는 작은 프로그램이다(L12).
2. 세션 간 격리 — git worktree(작업을 딴 폴더에 통째로 떼어 놓는 git 기능) 진입이 기본이다. 그래서 이 작업이 원래 폴더(master 작업 트리)를 건드리지 않는다.
3. 머지 자동화 — 마지막에 merge-master 서브에이전트가 코드를 합친다.

이건 standarda-template 에 들어있는 공통 스킬이고, 실제로는 popax 에서 한 달간 단계적으로 다듬어져(merge-master 도입 → SDD 재설계 → 마이그레이션 자동적용 → 교훈 전파) template 로 sync 됐다. 즉 한 프로젝트의 워크플로우 개선이 전 프로젝트로 환류된 결과물이다.

2. 오늘 따라갈 기능 — 회의록 세션 삭제

popax 회의록 목록에서 개별 세션을 삭제하는 기능. 한 줄로 이해되지만, /develop 의 가치를 보여주는 설계 결정이 하나 있다 — 소프트 삭제(행을 지우지 않고 ChatSession.active=False 로만 내림). 이 "의도"가 어떻게 스펙으로 적히고 검증되는지가 오늘의 핵심이다.

이 기능의 실제 산출물: - 백로그: docs/backlog/dev/done/D-260528224722-....md - 스펙: docs/specs/meeting_chat.md (세션 삭제 섹션) - 구현: meeting_chat/api/views.py 의 SessionDeleteAPIView - 문서: docs/features/meeting_chat_session_delete.md - 머지 커밋: d834b8d

3. 0~2단계 — 입력 파싱 · 모드 결정 · worktree 진입

/develop meeting_chat 세션 리스트에서 개별 회의록 세션 삭제  #D-260528224722

• 0. 입력 파싱: app_name=meeting_chat, task_description=..., 백로그 ID #D-260528224722 를 따로 보관.
• 1. 모드 결정 (기본 worktree): 슬러그(제목을 파일이름용으로 다듬은 짧은 이름, d-260528224722-session-delete)를 만들고 worktree 모드로 간다. 모델을 바꾸거나 마이그레이션(DB 표 구조를 바꾸는 작업)이 필요하면 무조건 worktree 다. (오타·문서 한 줄 같은 사소한 건 --inplace 허용)
• 2. worktree 진입: 따로 떼어 놓은 작업 공간을 만든다.

git worktree add ../worktrees/{slug} -b dev/{slug}
cd ../worktrees/{slug}
ln -s {project_root}/.env .env            # .env·credentials 는 심링크 재사용

왜 worktree? master 작업 트리를 그대로 둔 채, 완전히 분리된 폴더+브랜치에서 작업한다. 중간에 다른 일이 끼어들어도 섞이지 않고, 실패하면 worktree 만 버리면 된다.

4. 3~4단계 — 컨텍스트 로드(+lesson-finder) · 백로그 연동

• 3. 컨텍스트 로드 (병렬, read-only): docs/specs/{app}.md, 연관 코드, 컨벤션 문서를 동시에 읽는다. 이때 lesson-finder 서브에이전트가 팀 wiki 교훈 색인(/home/ubuntu/wiki/lessons/INDEX.md)에서 이번 task 에 관련된 다른 프로젝트의 교훈만 골라 온다. → 5·6단계에 반영.
• 4. 백로그 연동: 백로그 ID 가 있으면 그 항목을 읽어 작업 범위를 확정한다. 실제 D-260528224722 백로그에는 이미 권장 구현 방향과 결정사항이 적혀 있다:

- 제안: 권장 구현 방향 = 소프트 삭제. ChatSession.active 필드가 이미 존재하고
  모든 읽기 경로가 active=True 로 필터링하므로 active=False 로 처리하면
  마이그레이션·cascade·디스크 정리 없이 즉시 사라지고 복구도 가능.
- 참고: 삭제 권한 범위(확정): 조직 멤버 누구나. _get_session 통과 = 삭제 가능.

백로그는 단순 TODO 가 아니라 "배경 + 제안 + 결정" 을 담는다. 그래서 구현 전에 이미 방향이 서 있다.

5. 5~5.5단계 — 개발 계획 · 스펙 작성 ★SDD의 심장

• 5. 개발 계획 제시: 무엇을 어떤 순서로 바꿀지 사용자에게 보여주고 승인받는다.
• 5.5 스펙 작성/갱신 (필수, SKIP 없음): docs/specs/{app}.md 에 이번 사이클의 의도(Intent) 를 검증 가능한 명제로 적는다. 검증 가능한 명제란 나중에 "지켰나?"를 O/X 로 따질 수 있는 문장을 말한다. 이 문서가 이번 사이클의 믿을 기준 하나(SoT, Source of Truth)이고, 7단계 spec-verifier 의 채점 기준이 된다.

실제 docs/specs/meeting_chat.md 에 추가된 스펙(발췌):

## 직전 사이클 변경: 회의록 세션 삭제(소프트 삭제) (#D-260528224722)
... 삭제는 소프트 삭제(active=False)로 처리한다 ...

1. 삭제 엔드포인트 — DELETE /api/meeting-chat/<slug>/delete/ 가 존재한다.
   meeting_chat/api/views.py 의 SessionDeleteAPIView 가 delete 메서드를 제공한다.
2. 조직 스코프 접근 — _get_session(request.user, slug) 로 조회. 없으면 404.
   별도 소유자/admin 권한 검사는 하지 않는다.

핵심: 스펙은 산문이 아니라 "~가 존재한다 / ~하지 않는다" 같은 검증 가능한 명제 다. 그래야 나중에 기계(spec-verifier)가 "지켰나?"를 채점할 수 있다.

6. 6단계 — 구현

스펙을 기준으로 코드를 짠다. 세션 삭제는 4개 파일이 바뀌었다:

백로그가 "UserMemoryDetailAPIView.delete 패턴 참고", "무한스크롤 재렌더 대응 위해 이벤트 위임" 까지 짚어둔 덕에 구현이 헤매지 않는다. 컨텍스트가 앞 단계에서 이미 모였기 때문.

7. 7단계 — 검증 라운드 (통과 전 머지 금지)

구현이 끝나면 spec-verifier 서브에이전트가 5.5의 스펙 명제 하나하나를 변경 코드와 대조해 채점한다.

• 입력: docs/specs/{app}.md + 변경 파일 목록 + 구현 설명.
• 스펙이 없으면 BLOCKED — 5.5 를 건너뛰면 여기서 막힌다. (그래서 5.5가 필수)
• 7-α 재검증 루프: 미준수 항목이 하나라도 있으면 머지 차단. 고친 뒤 spec-verifier 재호출 → 통과할 때까지 8단계로 못 넘어간다.
• 단, 구현 중 "스펙보다 나은 방향"을 찾았고 사용자가 승인하면 → 5.5 로 돌아가 스펙을 patch 한 뒤 재검증 (스펙과 코드를 다시 맞춤).
• 검증 중 런타임 에러나 "안 돼/에러 나" 보고가 나오면, 분기 결정 전에 debug-server-log 서브에이전트(또는 메인)가 서버 로그부터 확인한다.

이 단계가 /develop 의 안전벨트다 — "내 의도(스펙)대로 실제로 됐는가"를 사람이 아니라 에이전트가 기계적으로 대조하고, 안 맞으면 머지를 막는다.

8. 8단계 — 문서 생성 (specs ↔ features 이원화)

7단계를 통과해야만 실행. 새 기능이면 /feature-doc 으로 사용자 관점 문서를 만든다. 실제 산출물 docs/features/meeting_chat_session_delete.md 의 "Design Decisions":

- 소프트 삭제(active=False) 채택: active 필드와 읽기 경로 필터가 이미 존재 →
  플래그만 내리면 즉시 제외. 마이그레이션 불필요, cascade 정리 불필요, 복구 가능.
- 권한 = 조직 멤버 누구나: 읽기/수정과 동일한 접근 모델 그대로.

문서가 둘로 나뉘는 게 SDD 의 특징이다:

9. 9~10단계 — 머지 · 마이그레이션 · 백로그 완료

• 9. merge-master 호출: 모든 검증 통과 후 머지 서브에이전트가 처리한다. 반환은 MERGE_OK / BLOCKED:* / WARN:*. 세션 삭제는 MERGE_OK → 머지 커밋 d834b8d.
• 9.5 마이그레이션 적용: MERGE_OK 일 때만, dev DB 에만 자동 migrate. 이 기능은 모델 변경(필드 추가)이 없어 → SKIP: no-migrations.
• (만약 새 필드를 추가했다면 여기서 makemigrations+migrate 가 돌고, 실패하면 BLOCKED: migrate-failed 로 10단계를 막는다. Production DB(실사용 DB)는 본 단계 범위 밖 — /release 가 담당.)
• 10. 백로그 완료 처리: backlog-manager 가 머지 해시를 동봉해 done 처리. 실제 백로그 꼬리:

- 완료일: 2026-05-28
- 머지 커밋: d834b8d
- 산출물: 소프트 삭제(active=False) 채택. ... 마이그레이션 없음.
  feature 문서 docs/features/meeting_chat_session_delete.md 생성.

10. 한눈에 보는 파이프라인 + 서브에이전트 5종

0 입력파싱 → 1 모드결정(worktree) → 2 worktree 진입
→ 3 컨텍스트 로드(병렬) +🤖lesson-finder
→ 4 백로그 연동 → 5 개발계획
→ 5.5 스펙 작성 ★ (specs/ = 검증가능한 의도 = SoT)
→ 6 구현
→ 7 검증 🤖spec-verifier (+7-α 재검증 루프: 미준수=머지차단 / 에러=🤖debug-server-log)
→ 8 문서 /feature-doc (features/ = 사후 사실)
→ 9 🤖merge-master → 9.5 마이그레이션(dev) → 10 🤖backlog-manager 완료

부록 — 이 기능은 실제로 이렇게 "입력"됐다

위 0~10단계는 자동으로 굴러간 게 아니다. 시작은 사람이 친 자연어 한 줄이었다. popax 세션 기록(2026-05-28)에 남은 실제 입력 순서:

① 아이디어 한 줄 (22:45)

"백로그에 meeting chat 하단에 회의록 세션 리스트가 있는데 개별 회의록 세션을 삭제할 수 있는 기능도 넣고 싶은데 어떻게 해야할까"

→ backlog-manager 가 받아 백로그 #D-260528224722 등록 (소프트 삭제 방향 정리, 권한 범위는 "미결"로 메모).

② 권한 결정 (22:49) — 되물어온 질문에 선택

"회의록 세션 삭제 권한을 누구에게?" → 조직 멤버 누구나 (현 접근모델과 동일)

→ 백로그의 미결 항목이 "확정"으로 갱신.

③ /develop 호출 (22:54)

/develop meeting_chat 회의록 세션 삭제 기능 (#D-260528224722).
소프트 삭제(ChatSession.active=False) 방식: DELETE /api/meeting-chat/<slug>/delete/
엔드포인트 추가(_get_session 통과 = 조직 멤버 누구나 삭제 가능),
chat_home.js 세션 카드에 삭제 버튼(이벤트 위임 + confirm + CSRF DELETE → 카드 DOM 제거).

읽는 법: 사람이 직접 친 건 ①의 자연어 한 줄뿐이다. 거기서 백로그 등록(①) → 권한 결정(②) → /develop(③) 으로 이어졌다. ③의 프롬프트가 이미 "소프트 삭제·엔드포인트·이벤트 위임"까지 구체적인 이유는, ①②를 거치며 그 내용이 백로그에 정리돼 있었기 때문이다 — 앞 단계가 컨텍스트를 모아준 덕에 develop 호출이 정확해진다. "좋은 프롬프트를 한 번에 쓰는 것"이 아니라, 백로그·결정 과정을 거쳐 의도를 누적한 결과다.

오늘 정리 + 다음

• 정리: /develop 은 "백로그(의도) → 스펙(검증 가능한 의도, SoT) → 구현 → spec-verifier 검증(통과 전 머지 금지) → feature 문서(사실) → merge-master 머지 → 마이그레이션 → 백로그 완료"를 한 흐름으로 돈다. 핵심은 5.5 스펙과 7 검증이 짝을 이뤄 "내가 의도한 대로 실제로 됐는가"를 기계적으로 보장하는 것이다. worktree 로 떼어 놓고, 서브에이전트 여럿을 동시에 돌려 안전하고 빠르게.
• 흔한 함정: 5.5 스펙을 대충 쓰면 7단계가 헛돈다. 스펙은 산문이 아니라 "~가 존재한다 / ~하지 않는다" 검증 가능한 명제로 써야 spec-verifier 가 채점할 수 있다. 그리고 스펙 없이 구현부터 하면 7단계에서 BLOCKED.
• 다음 시간: spec-verifier / merge-master 같은 서브에이전트 내부를 열어보고, 직접 작은 기능을 /develop 으로 한 바퀴 돌려보기.
• 자습 권장: 자기 프로젝트의 docs/specs/{app}.md 와 docs/features/ 를 열어, 같은 기능이 "의도"와 "사실"로 어떻게 나뉘어 적혔는지 비교해보기. popax 의 docs/features/meeting_chat_session_delete.md 가 짧고 좋은 예시.