sy/dev
Project
6 min read

Braincrew Wiki — Obsidian으로 쓰고 AI Routine이 정제하는 팀 위키

팀 지식을 raw notes에서 정제된 위키 페이지로 변환하는 자동화 시스템. Obsidian raw 메모 → GitHub Action → AI가 정제한 PR → 발행 완료까지 인간과 AI의 git author 분리로 운영합니다.

Series

Harness 만들기
  1. 1Harness 만들기 1편 — 왜 만들고 어떻게 짰나
  2. 3Braincrew Wiki — Obsidian으로 쓰고 AI Routine이 정제하는 팀 위키

팀이 망각하는 것들

팀이 커지면서 피할 수 없는 문제가 생겼습니다. "어, 이거 이미 해본 거 아닌가?", "왜 이런 결정을 했지?", "마지막 배포 상황이 뭐였더라?"

문서는 많은데, 정제되지 않았습니다. Slack 대화는 흩어져 있고, 노션 페이지는 중복되고, 결정의 이유는 사라집니다.

Karpathy의 LLM-wiki 패턴을 보니 아이디어가 명확했어요.

raw → AI 정제 → 정책 결정 → 발행

Braincrew Wiki는 이 흐름을 팀에 맞게 구현한 것입니다.

세 가지 계층

[Obsidian raw/] 
  ↓ (개인 메모, 자유로운 형식)
[GitHub Action: wiki-curator]
  ↓ (자동 정제, PR 생성)
[Reviewed PR]
  ↓ (팀 승인)
[docs/wiki/] (배포된 정식 위키)

1단계: raw/ — 자유로운 메모

Obsidian에서 raw/ 폴더에 어떤 형식으로든 적습니다.

# 05-29 배포 후처리
- 카나리 배포 → 5% → 10% → 100% (2시간 소요)
- DB migration 완료 (no downtime)
- 모니터링 대시보드에서 P99 latency ↓3ms
- 팀 슬랙에서 조경 지적: "조회 API 한번에 여러 user fetch, N+1 아닌가"
  - 관찬이가 내일 보자고 함
 
# AsyncIO 팁 스크랩
Nate의 슬랙:
> asyncio.create_task 는 즉시 실행되지만, gather는 await 시점에 실행됨
> 문서에서 놓친 부분이 있음

형식, 길이, 완성도 상관없습니다. 나중에 정제해요.

2단계: wiki-curator (GitHub Action)

주 3회 실행:

# .github/workflows/wiki-curator.yml
on:
  schedule:
    - cron: '0 9 * * 1,3,5'  # 월·수·금 아침 9시

이 Action이 하는 일:

  1. raw/ 폴더의 모든 .md 파일 수집
  2. Claude API로 정제 프롬프트 실행
  3. 중복 제거, 카테고리화, 인용문 제거
  4. docs/wiki/ 디렉토리에 정식 위키 페이지 생성
  5. 개인의 git author를 AI author로 변경
  6. Pull Request 생성 (자동 merge 아님)
# wiki-curator가 생성한 커밋
Author: Braincrew Wiki Curator <bot@braincrew.ai>
    
    wiki: deployment-incident-2026-05-29
    
    - 5월 29일 카나리 배포 결과 요약
    - latency 개선 (P99 -3ms)
    - TODO: N+1 쿼리 최적화 (담당: 관찬)

여기서 핵심은 팀 멤버의 이름이 PR 이력에 남지 않는다는 거예요. 그 대신 위키 본문에는 "조경이 제기한 이슈" 같은 식으로 맥락이 남습니다.

3단계: Review & Merge

팀이 PR을 열어서:

  • "이 요약 맞나?" 확인
  • 누락된 부분 comment로 추가
  • raw/ 수정 → wiki-curator 다시 실행
  • 승인 → main merge → Vercel 배포

구현: Next.js 16 + Bun

wiki 페이지는 Next.js로 렌더됩니다.

// app/wiki/[slug]/page.tsx
import { getWikiPages, getWikiContent } from '@/lib/wiki'
 
export default async function WikiPage({ params }) {
  const content = await getWikiContent(params.slug)
  const pages = await getWikiPages()
  
  return (
    <div className="prose">
      <h1>{content.title}</h1>
      <meta name="git-author" content={content.gitAuthor} />
      <WikiContent markdown={content.body} />
      <WikiMeta createdAt={content.createdAt} lastReviewedAt={content.lastReviewedAt} />
    </div>
  )
}

깃 author가 "Braincrew Wiki Curator"면, 페이지 하단에 작은 뱃지:

이 페이지는 AI가 정제했습니다. 원본 노트 보기 • 리뷰 PR

왜 이렇게 했나

  1. 속도: 개인이 "완벽한 문서"를 쓸 때까지 기다리지 않습니다. raw → 자동 정제 → 팀이 손봄.

  2. 일관성: AI가 tone, structure, 중복 제거를 자동으로 맞춥니다.

  3. 추적성: git author 분리로 "인간의 의견" vs "AI의 정제"를 구분. 누군가는 '이건 AI가 다시 쓴 거고', '이건 원본 의견이구나' 즉각 알 수 있어요.

  4. 부담감 없음: raw/에 "불완전한 메모"를 마음껏 쓸 수 있어요. 나중에 정제되니까요.

Braincrew 실제 사용 사례

  • 배포 후처리 자동 기록: 슬랙 스레드 → raw/ → PR → 위키 (2시간 내)
  • 아키텍처 결정 기록: 회의 노트 → raw/ → 정제된 ADR (Architecture Decision Record) → 위키
  • 팀 코딩 팁: 누군가 "이것도 모르네?"하면 → raw/ → 튜토리얼 페이지
  • 온보딩 자료: 신입이 질문하면 → Q&A raw → 온보딩 가이드 페이지

주의점

  • raw/에만 쓰세요: main에 직접 쓰면 wiki-curator가 덮어씁니다.
  • 민감한 정보는 제외: HR, 급여, 개인정보는 raw/에 절대 금지. 자동 정제 대상에서 제외 규칙 설정.
  • AI가 모든 걸 이해하지 못할 수 있음: 팀 context가 부족하면 PR comment로 보충.

다음 편 예고

Harness 시리즈는 여기까지입니다. 1편(skills·agents·hooks) → 2편(듀얼 메모리) → 3편(이 wiki 시스템).

다음엔 개별 skill을 만드는 방법이나 실전 workflow (블로그 자동 발행, PR 리뷰, 일정 추가)를 다룰 예정입니다.

참고

Comments