@brxce/mcp-server 1.1.16 → 1.1.18

package/skills/brxce-mcp/references/workflows.md

@@ -0,0 +1,276 @@
+# BRXCE MCP Workflows
+
+실전에서 자주 쓰는 워크플로우 카탈로그. 각 패턴은 step-by-step + 권장 도구 + 안전 체크를 포함한다.
+
+---
+
+## 1. 인박스 트리아지 (Inbox Triage)
+
+backlog 상태의 노드를 빠르게 정리. **인박스 = 내 워크스페이스의 `status=backlog` 전부** (archived/deleted 제외). 프로젝트 하위 작업도 backlog면 여기에 포함됨.
+
+```
+1. brxce_workspace_inbox({ workspaceId, limit: 200 })
+   → summary.inboxCount 확인, inbox[] 배열 처리
+
+2. 각 노드를 카테고리별로 분류 (head로 5~10건씩)
+   - 즉시 완료 가능 → batch_actions(action: complete, nodeIds: [...])
+   - 다른 부모로 이동 → batch_actions(action: move, nodeIds, params: {newParentId})
+   - 노이즈/중복 → batch_actions(action: archive)
+   - 검토 필요 → 본인 assignee + 우선순위 설정 (update_worknodes)
+
+3. 인박스 재확인 → 0건 또는 진짜 검토 필요한 항목만 남도록
+```
+
+**팁**: 같은 부모로 이동할 그룹은 한 번의 `batch_actions(action: move)` 호출로 묶을 것. 50건씩 페이지네이션으로 처리.
+
+**주의**: `my/shared` 분리는 폐기됨 (1.1.18+). 응답은 단일 `inbox` 배열 + `inboxCount`. 1.1.17 이하 `myInbox`/`sharedInbox` 분리 응답은 legacy.
+
+---
+
+## 2. 일일 보고 (Daily Report)
+
+매일 아침 어제 무엇을 끝냈고 오늘 무엇을 할지 정리.
+
+```
+1. brxce_daily_report(workspaceId)
+   → 오늘 완료된 노드, 충족 미달 AC, 산출물 누락 자동 집계
+
+2. brxce_my_work(workspaceId, mode: "active")
+   → 진행 중인 작업 리스트
+
+3. brxce_goal_progress(workspaceId)        # goalId 생략 = 전체 goal 일괄
+   → 목표별 AC 충족률
+
+4. (선택) brxce_workspace_statistics(workspaceId)
+   → memberStats, dueDates 등 매크로 통계
+```
+
+**팁**: `daily_report` 응답의 `unmetCriteria` 항목들이 우선순위 1순위. 거기 노드를 `worknode_detail`로 열어 상세 검토.
+
+---
+
+## 3. GitHub 이슈 → BRXCE 워크노드 동기화
+
+새 GitHub 이슈가 만들어지면 BRXCE에 대응 task 생성.
+
+```
+1. brxce_create_worknodes({
+     worknodes: [{
+       title: "[Bug] 로그인 시 401 — 토큰 갱신 누락 (#123)",
+       nodeType: "task",
+       parentNodeId: <"이슈 처리" 프로젝트 UUID>,
+       priority: "high",
+       acceptance_criteria: [
+         { title: "재로그인 없이 토큰 자동 갱신" },
+         { title: "401 에러 로깅 + 알림" },
+       ],
+     }],
+     preview: false,
+   })
+
+2. brxce_add_tags_to_worknode({
+     worknodeId: <위에서 받은 ID>,
+     tagIds: [<"issue-created" 태그 UUID>],
+     workspaceId,
+   })
+
+3. (선택) brxce_create_comment({
+     nodeId: <ID>,
+     content: "GitHub: https://github.com/foo/bar/issues/123",
+   })
+```
+
+**팁**: 태그 ID는 `brxce_search_tags(query: "issue-created")` 한 번으로 캐시. 반복 호출하지 말 것.
+
+---
+
+## 4. 회의 준비 + 노트 작성
+
+회의 자동 리뷰 → 아젠다 → 노트/결정 → 후속 작업.
+
+```
+1. brxce_create_meeting({
+     workspaceId,
+     title: "Sprint 23 Review",
+     scheduledAt: "2026-04-15T09:00:00Z",
+     preview: true,    # 먼저 dry run으로 review period + 완료 워크노드 확인
+   })
+
+2. (검토 후) 동일 호출에 preview: false
+   → meetingId 받음
+
+3. brxce_add_agenda_item({
+     meetingId,
+     title: "Sprint 23 결과 리뷰",
+   })
+   → itemId 받음
+
+4. 회의 진행 중:
+   brxce_add_agenda_note({ meetingId, itemId, content: "..." })
+   brxce_add_meeting_decision({ meetingId, title: "다음 sprint는 X에 집중" })
+
+5. 회의 종료:
+   brxce_update_meeting({ meetingId, changes: { status: "completed" }, preview: false })
+```
+
+**팁**: agenda note는 1.1.16+에서 fully working. 이전 버전은 add/list/update/delete 모두 404였음.
+
+---
+
+## 5. 멤버별 작업 리뷰 (1:1 준비)
+
+각 팀원의 진행 중인 작업과 미달성 AC를 한눈에.
+
+```
+1. brxce_search_users(query: "member name")
+   → userId 확인
+
+2. brxce_worknodes_by_member({
+     workspaceId,
+     userId: <user UUID>,    # memberId alias도 동일
+     status: "in_progress",
+     limit: 50,
+   })
+
+3. 각 노드에 대해 worknode_detail로 AC 진행도 확인
+4. 막힌 작업이 있으면 brxce_create_comment로 이슈 코멘트
+```
+
+**팁**: 1.1.16부터 `userId`와 `memberId` 둘 다 alias로 동작. 이전 버전은 `memberId`만.
+
+---
+
+## 6. 태그 거버넌스 (Tag Governance)
+
+중복/미사용 태그 정리.
+
+```
+1. brxce_get_tag_stats(workspaceId)
+   → unused tags, total assignments
+
+2. 미사용 태그 발견 시:
+   brxce_delete_tag({ workspaceId, tagId })
+
+3. 새 카테고리/태그 생성:
+   brxce_create_tag_category({ workspaceId, name: "환경", slug: "environment" })
+   brxce_create_tags_batch({
+     workspaceId,
+     tags: [
+       { name: "Production", categoryId: <위에서 받음> },  # slug 자동 생성
+       { name: "Staging", categoryId: <...> },
+       { name: "Local", categoryId: <...> },
+     ],
+   })
+
+4. brxce_batch_assign_tags({
+     workspaceId,
+     worknodeIds: [...],
+     tagIds: [<production 태그 UUID>],
+   })
+```
+
+**팁**: `create_tag` slug는 1.1.15+부터 자동 derive (`Backend/Node.js` → `backend-nodejs`). 명시 가능.
+
+---
+
+## 7. 대량 검색 → 일괄 변경 (Bulk Update)
+
+특정 조건의 모든 노드에 동일 변경 적용.
+
+```
+1. brxce_filter_worknodes({
+     workspaceId,
+     status: ["backlog"],
+     tags: ["urgent"],
+     pageSize: 100,
+   })
+   → worknodes[] + total
+
+2. 결과에서 nodeId 추출
+
+3. brxce_batch_actions({
+     action: "update-priority",
+     nodeIds: [...],
+     params: { priority: "critical" },
+   })
+```
+
+**팁**: `filter_worknodes`는 1.1.15+에서 도입된 새 backend 라우트. 이전 버전은 404. 큰 결과는 페이지로 나눠 호출.
+
+---
+
+## 8. 워크스페이스 델타 동기화 (Incremental Sync)
+
+외부 시스템(Notion 미러, 백업 등)에 최신 변경만 sync.
+
+```
+1. brxce_workspace_delta({
+     workspaceId,
+     sinceVersion: <마지막 동기화 버전>,
+     maxChanges: 100,
+   })
+
+2. response.changes를 순회해서 외부 시스템 갱신
+3. response.currentVersion (또는 truncated 시 nextSinceVersion) 저장
+4. truncated: true이면 다음 호출에서 nextSinceVersion부터 이어가기
+```
+
+**경고**: `sinceVersion: 0` 첫 동기화는 800KB+ 가능. 반드시 `maxChanges` 명시 + 페이지 처리.
+
+---
+
+## 9. 반복 작업 템플릿 (Recurring)
+
+매주/매일 자동 생성되는 작업.
+
+```
+1. brxce_create_recurring_template({
+     workspaceId,
+     title: "주간 회고",
+     rrule: "FREQ=WEEKLY;BYDAY=FR",
+     nodeType: "task",
+     priority: "medium",
+     timezone: "Asia/Seoul",
+   })
+
+2. 백엔드가 cron으로 매주 금요일에 실제 task 자동 생성
+3. brxce_list_recurring_templates(workspaceId)로 활성 템플릿 확인
+4. 변경 필요 시 brxce_update_recurring_template
+```
+
+**팁**: AC가 필요한 task는 템플릿에 `acceptance_criteria` 함께 정의 (작성 시점에 제공해야 함, 자동 생성된 인스턴스에는 없음).
+
+---
+
+## 10. 클린업 (테스트 데이터 제거)
+
+세션 끝낼 때 테스트 노드 정리.
+
+```
+1. brxce_read_worknodes({
+     workspaceId,
+     query: "[테스트]",       # title prefix로 검색
+     limit: 200,
+   })
+
+2. brxce_batch_actions({
+     action: "delete",        # soft delete
+     nodeIds: [...],
+   })
+
+3. (필요 시) 각 노드를 brxce_permanent_delete_worknode로 hard delete
+   → cascade로 children, criteria, comments, tagRelations 모두 제거
+```
+
+**경고**: `permanent_delete`는 owner만 가능. cascade가 큰 트리에서는 시간 걸릴 수 있음.
+
+---
+
+## 안티 패턴 (피해야 할 것)
+
+- ❌ N개 노드에 N번 `update_worknodes` 호출 → ✅ `batch_actions` 한 번
+- ❌ task 생성 시 AC 생략 → ✅ 항상 최소 1개
+- ❌ `preview` 명시 없이 create/update → ✅ 명시적 `false`
+- ❌ UUID를 `query`로 read → ✅ `worknodeIds` / `nodeIds`
+- ❌ workspace_delta sinceVersion=0 무한정 → ✅ maxChanges + 페이지
+- ❌ permanent_delete 후 즉시 inbox 신뢰 → ✅ 1.1.16+에서 자동, 그 미만은 한 번 더 read