user_brief›문서›user_brief 설계·운영 (design)
33.1 KB · 수정 2026-06-05 01:05
목차

user_brief 설계·운영 (design)

user_brief 시스템 설계·운영 문서입니다. 기존 루트 HANDOFF.md의 생성/스크립트·핵심 학습·작업 방식·재실행과 폐지된 PLAN.md 전체를 위치만 옮긴 것(내용 보존)입니다.

생성/스크립트 파일 (현재 — M4)

핵심 학습 (재현용)

작업 방식 (채티 원칙 — 유지)

재실행

# 데이터 추출(노션 재접속 — 필요시만). M4: 출력이 inbox/notion_export/ staging이라 live projects/는 안전.
#  승격(staging→projects/)은 수동. 트래커 JSON(data/)은 여전히 갱신되므로 신중히.
C:\dev\user_brief\.venv\Scripts\python.exe C:\dev\user_brief\scripts\export_notion.py
# SQLite 적재(로컬, 멱등 — tasks+project / docs_pages, 시작 시 manifest 검증). 단독 검증: validate_manifest.py
C:\dev\user_brief\.venv\Scripts\python.exe C:\dev\user_brief\scripts\build_db.py
# 리포트 재빌드(단일 커맨드; build_db→build_brief→copy→render_docs→sources→build; -Verify로 Playwright)
powershell -ExecutionPolicy Bypass -File C:\dev\user_brief\scripts\rebuild_report.ps1 -Verify
# 로컬 서빙(독립·정적·SARA 무관; http://127.0.0.1:8788)
powershell -ExecutionPolicy Bypass -File C:\dev\user_brief\scripts\serve_report.ps1

구현 계획 (구 PLAN.md)

아래는 폐지된 루트 PLAN.md 전체를 위치만 옮긴 것입니다(본문 보존, 헤딩만 한 단계 낮춤).

user_brief 구현 계획 (v7 · 멀티프로젝트 + user_brief 프로젝트 편입 완료)

목적: SARA 노션 콘텐츠(로컬 파일)를 생성형(비-LLM) 정적 HTML 읽기전용 리포트로 변환. 재빌드=갱신=토큰 0. 기준일: 2026-06-03 · 시드: C:\dev\user_brief\HANDOFF.md · 합의: agent-dialogue-hub report#1, feedback#4 v1→v2: prop_val 분리 · 영문 alias 스키마 · SQLite 복사 파이프라인 · 마일스톤 분리(M1/M2/S6) 반영. v2→v3: M2 구현 완료 반영 — S4 페이지 5종(index/tracker/charts/roadmap/pages) 확정 · docs_pages 테이블+정적 복사(report/static/docs/) · scripts/rebuild_report.ps1(-Verify) · Playwright(Node @playwright/test) 검증 셋업. v3→v4: S6 재정의 — SARA 비종속 독립 서빙. 로컬 1차 = scripts/serve_report.ps1(npx serve report/build, 127.0.0.1:8788, 정적·토큰 0). 외부 공유(Tailscale)=대기 항목. SARA는 정적 디렉토리 서빙 인프라(StaticFiles)가 없어 끼우지 않음(분리 부담 회피). v4→v5: 멀티프로젝트 전환 계획 추가(§13). 합의 #34(에이전트 시드/메모리: sidecar manifest·토큰0 BRIEF·decisions.json) + #35(멀티프로젝트·6분류·inbox)를 통합한 8단계 마이그레이션 + 코디 지시문(CODI_M4_multiproject_seed.md) 계획. v5→v6: M4 구현 완료. 8단계 전부 단계별 검증 통과(projects/sara/ 이동·docs_manifest.json 카탈로그·URL 네임스페이스·tasks.project·decisions.json·토큰0 BRIEF.*·inbox/·export_notion staging). rebuild_report.ps1 -Verify Playwright 8/8. 로컬 커밋(push 없음). §13에 구현 결과 반영.

0. 목적 / 범위

1. 현재 기준 (완료된 것 — 사실 확인 완료)

2. 확정 전제 (재논의 금지)

3. 파이프라인 개요

[노션] --(S1 완료)--> docs/*.md + data/트래커.json
                                   |
                          (S2a) build_db.py  [prop_val ← notion_props.py]
                                   v
                        data/user_brief.sqlite (tasks 89행, 영문 alias)
                                   |
                   빌드 직전 복사: data/user_brief.sqlite
                                   → report/sources/user_brief/user_brief.sqlite
                                   v
                    (S3a) Evidence 프로젝트 + sqlite 소스 + DataTable 1개   ← M1 끝
                                   |
                    (S4) docs_pages·차트·로드맵·docs 링크                     ← M2
                                   v
                          (S5) npm run build → build/ 정적 HTML
                                   |
                                   v
                              (S6) SARA 서빙                                  ← 별도 승인

각 단계는 새 파일·디렉토리만 추가(또는 export_notion의 prop_val 분리 리팩터 1건)하므로 격리 롤백 가능.

4. 단계별 상세 (입력 / 작업 / 출력 / 검증기준 / 되돌리기)

S1. 추출 — ✅ 완료

S2a. SQLite 적재 (tasks) — M1

S3a. Evidence DB연결 + DataTable 1개 — M1

S4. 페이지 구성 — M2 ✅ 완료

페이지 5종(report/pages/): - index.md: BigValue(총 89·완료·진행중·대기·완료율) + 상태 분포 막대 + Phase별 완료율 막대. - tracker.md: 풀 <DataTable>(검색·정렬, rows=100로 89행 전수 표시) + 드롭다운 필터(상태·Phase·담당·그룹1). DuckDB-WASM 클라이언트 필터 — "전체"(LIKE '%')가 기본값. - charts.md: 상태 도넛(ECharts) + Phase·담당·우선순위 막대. - roadmap.md: Phase×상태 매트릭스(조건부 집계, 빈 Phase='' → '미지정') + Phase별 완료율 BigValue({#each}). - pages.md: docs_pages 목록 + 원본 .md 정적 링크(/docs/<filename>, rel="external"). - docs_pages 테이블(build_db.py): docs/*.md → title/filename/rel_path/size/mtime(8행). 소스: report/sources/user_brief/docs_pages.sql. - docs 정적 복사: docs/*.md → report/static/docs/(생성물·gitignore). 빌드 시 report/build/docs/로 서빙. - 검증: 각 페이지 무에러 렌더(Playwright), 상태/Phase/담당/그룹 드롭다운 필터 동작, 상태별·Phase별 건수 합 == 89.

S5. 정적 빌드 + 검증 — M2 ✅ 완료

S6. 서빙 — 독립 (SARA 비종속)

5. 갱신 파이프라인 (단일 커맨드 — M2 ✅ 완료)

6. 목표 디렉토리 구조

C:\dev\user_brief\
  docs/                      # (기존) 노션 페이지 8 .md
  data/
    ✅ 작업 트래커 ….json     # (기존) 시드
    ✅ 작업 트래커 ….md
    user_brief.sqlite        # (신규 S2a)
  scripts/
    export_notion.py         # (기존, prop_val 분리 리팩터)
    notion_props.py          # (신규 S2a) 공용 prop_val
    build_db.py              # (신규 S2a)
    rebuild_report.ps1       # (신규 M2)
  report/                    # (신규 S3a~S5) Evidence 프로젝트
    sources/user_brief/
    pages/
    build/                   # (신규 S5) 정적 산출물
  HANDOFF.md / PLAN.md

7. .gitignore (보완 항목)

node_modules/
report/build/
report/.evidence/          # 캐시 실제명은 S3a 빌드 후 정정
report/sources/**/*.sqlite
data/*.sqlite
*.log

8. 마일스톤 분리

9. 구조 원칙 (추후 다른 리포 HTML 브리핑 확장 대비)

추후 다른 리포도 "데이터/JSON → SQLite → Evidence 정적 HTML" 대상. 지금 범용 프레임워크/공통 라이브러리 만들지 않는다(과한 추상화 금지). 대신:

  1. 리포 특화 값(리포명·입력 경로·COL_MAP·출력 SQLite명)은 build_db.py 상단 한 블록에 상수로 모은다.
  2. 디렉토리 패턴을 리포 간 동일하게: <repo>/data/*.sqlite, <repo>/scripts/build_db.py, <repo>/scripts/notion_props.py, <repo>/report/. 다른 리포는 이 골격을 복제해 상단 상수만 변경.
  3. notion_props.py는 리포 독립적(특정 리포 값 하드코딩 금지) — 추후 공용 모듈 후보.
  4. rebuild_report.ps1(M2)도 리포명/경로를 상단 변수로.

→ 목표는 "복제로 확장 가능한 단순 골격". 공통화·플러그인화는 리포 2~3개 경험 후 별도 판단.

10. 위험 작업 (별도 승인 필요)

11. 미결정 / 해소된 질문

12. 성공 기준

13. 멀티프로젝트 전환 (합의 #34 + #35) — 8단계 마이그레이션 + 코디 지시문 계획

상태: 구현 완료(8단계 + 마무리, 로컬 검증 통과·로컬 커밋 8d88e49·push 없음). 이 절이 마이그레이션의 단일 계획 출처. 코디 지시문 = CODI_M4_multiproject_seed.md(이 절을 그대로 구현). 실측 결과: docs_pages 7·tasks 89(+project)·BRIEF.sara.md 8,494자(≤12,000)·Playwright 8/8. 근거: adh_report_34.md(#34) · 협의 결과 #35(inbox/멀티프로젝트) · GPT_상의문_*.

13.1 배경·확정 (재논의 금지)

13.2 SARA 문서 분류·식별자 매핑 (확정 — 이번 마이그레이션 적용)

이동만(파일명·H1 보존). manifest title이 표시명(이모지 제거), id 전역 유일(<project>-<slug>).

order 현재 파일(보존) id category title(표시) seed
1 SARA.md sara-hub index SARA true
2 🗂️ 세부 상의 — SARA 시스템 설계.md sara-design-system design SARA 시스템 설계 false
3 📦 SARA 통합 인수인계서 (최신·단일 시드).md sara-handoff handoff SARA 통합 인수인계서 true
4 🗄️ 인수인계서 이력 아카이브.md sara-archive archive 인수인계서 이력 아카이브 false
5 🚨 [긴급·1순위] 멀티에이전트 통합 아키텍처 — 세부 상의 (cmdboard 자원 참조).md sara-multiagent design 멀티에이전트 통합 아키텍처 false
6 협의 결과 — (다) CLI 러너 설계 확정 (hub #28, 2026-06-01).md sara-cli-runner design CLI 러너 설계 확정 false
7 🔍 EVALUATOR 웹페이지 실사용 평가 — 설계 제안.md sara-evaluator design EVALUATOR 웹페이지 평가 false
8 memory.md (신규 작성) sara-memory memory 프로젝트 메모리 true

13.3 8단계 마이그레이션 상세 (각 단계 후 검증 — 코디 지시문 = 이 순서)

① manifest 스키마: 루트 docs_manifest.json 생성. 기존 docs/_order.json(7) → manifest로 흡수(필드 id·project·filename·category·order·title·topics·seed). SARA 8행(기존 7 + memory). 검증 함수(scripts/validate_manifest.py 또는 build_db 내): projects/*/*.md ⟷ manifest 1:1, 누락·title 공백 → 실패. ② 이동: projects/sara/ 생성, git mv docs/*.md(7) → 파일명 보존. docs/_order.json 제거(manifest로 대체). projects/sara/memory.md 신규(스타터). data/ 불변. ③ build_db·render_docs manifest 전환 + URL 네임스페이스: - build_db: DOCS_DIR/DOCS_ORDER glob → manifest 기준. docs_pages 스키마 확장(+project·category·rel_path·html_path), title=manifest 출처(H1 아님), sort_order=manifest order, +seed. 누락 시 빌드 실패. tasks 로직 이 단계 불변. - render_docs: DOCS_SRC → manifest 기준 projects/<P>/<filename>. 출력 report/static/docs/<project>/<stem>.html. stale HTML 청소 범위 확장(하위 폴더 통째 재생성). breadcrumb 프로젝트 인지. - Evidence: pages/SARA/docs.md 링크 /docs/sara/<stem>.html·WHERE project='sara'. pages/SARA/index.md iframe /docs/sara/SARA.html. verify.spec.ts URL·iframe 갱신(EXPECT_DOCS=7 유지). rebuild_report.ps1 청소 범위·render 호출 정합. ④ tasks.project + 백필: build_db에서 tasks에 project 컬럼 추가, 기존 89행 기본값 'sara'. COL_MAP/적재 로직 외 불변. group1/2 유지. ⑤ decisions.json 통합: data/decisions.json 생성(active만, 필드 id·project·status·title·decision·source). 시드 = HANDOFF 확정결정 + #34/#35 핵심. 글로벌은 project:"global". build_brief가 읽음(UI 추가 없음). ⑥ BRIEF..md + 글로벌 인덱스: scripts/build_brief.py(토큰0 결정형). manifest category 포함규칙 + tasks 롤업 + decisions로 BRIEF.sara.md 조립. 12,000자 초과 시 빌드 실패. BRIEF.global.md = 프로젝트명·한줄목표·active만(아주 작게). rebuild_report.ps1에 build_brief 단계 추가. ⑦ inbox + validator 경로 좁히기: inbox/ 생성, 루트 임시물(adh_report_*·CODI_M1~M3b·GPT_상의문_*) 이동(삭제 아님). validator는 projects/*/*.md만 검사, inbox 완전 제외. .gitignore 정합(inbox 추적 유지·빌드 제외). docs_pages·BRIEF·render에 inbox 비노출 보장. ⑧ export_notion staging 격하: export_notion.py의 DOCS 출력 → inbox/notion_export/만. live(projects/) 덮어쓰기 금지·경고 주석. 이번 작업서 실행 안 함(코드 변경만).

마무리(검증·문서·시드체인): 전체 rebuild_report.ps1 -Verify(Playwright 전부 통과)·시크릿 누수 0. HANDOFF·PLAN을 "구현 완료"로 갱신. #34 시드 체인 마감: CLAUDE.md/PROMPT_SNIPPET.md(글로벌 시작 관례 — 새 대화: HANDOFF→PLAN→BRIEF.global→해당 BRIEF. 순으로 읽기)를 최소 내용으로 작성. 로컬 커밋(push 제외).

13.4 코디 지시문 계획