팀의 진짜 엔지니어링 기록은 매일 삭제하는 AI 세션에 있습니다

팀의 진짜 엔지니어링 기록은 커밋 히스토리(commit history)에 있지 않습니다. 그것은 모두가 매일 닫고 잊어버리는 AI 세션(AI sessions)에 있습니다.

커밋은 "인증 리팩토링(refactor auth)"이라고 말합니다. 하지만 어떤 두 가지 접근 방식을 시도했는지, 어떤 것이 작동하지 않았는지, 어떤 문서가 결정을 내리는 데 도움을 주었는지, 또는 왜 명백한 경로를 거부했는지는 알려주지 않습니다.

"우리가 실제로 이것을 어떻게 결정했는가"에 대한 내용은 항상 유실되었습니다. 그것은 오직 누군가의 머릿속에만 존재했을 뿐, 결코 기록된 적이 없었습니다.

이제 상황이 바뀌었습니다. 당신의 팀은 이제 Claude Code와 Codex로 코드를 작성하며, 그 모든 판단 과정(judgment calls)이 처음으로 온전히 기록됩니다. 그것들은 세션(session) 안에 있습니다. 그리고 탭을 닫으면 그것들은 사라집니다.

저 또한 한두 번 이상 이런 경험을 했습니다. 왜 모듈이 그런 방식으로 분할되었는지 기억할 수 없었고, 커밋과 PR(Pull Request)은 아무것도 말해주지 않았으며, 결국 몇 달 전 제 세션 중 하나에서 그 이유를 찾아냈습니다. 그것은 오직 그곳에만 존재했으며, 하마터면 탭과 함께 사라질 뻔했습니다.

세션(session)의 실제 정의

이것이 핵심이기 때문에 정확하게 정의할 가치가 있습니다.

AI 세션은 단순한 채팅 로그(chat log)가 아닙니다. 그것은 문제가 해결되는 과정의 기록(transcript)입니다: 무엇을 시도했는지, 무엇이 고장 났는지, 어떤 문서를 읽었는지, 매 단계에서의 판단(judgment) 등입니다. 또한 그것은 당신이 작업하던 정확한 git 리포지토리(repo)에 고정되어 있습니다.

달리 표현하자면, 세션은 어떤 일을 수행하는 데 필요했던 모든 컨텍스트(context)를 하나의 단위로 묶어놓은 것이라고 할 수 있습니다.

이는 커밋과 PR보다 한 단계 진보한 것입니다. 커밋은 사람이 사후에 작성한 손실이 있는 요약(lossy summary)입니다. 세션은 작업이 일어나는 과정 그대로를 기록한 것입니다. 우리는 이전에는 이런 것을 가져본 적이 없습니다.

문제는 이것이 한 개인의 로컬 채팅(local chat)에 존재하며, 탭을 닫을 때 소멸한다는 점입니다. 따라서 당신의 팀은 이제 역사상 가장 훌륭한 엔지니어링 기록을 만들어내면서도, 매일 그것을 삭제하고 있는 셈입니다.

팀을 운영하는 입장에서 이것이 중요한 이유

세 가지 구체적인 비용이 발생합니다.

누군가 떠나면, "방법(how)"도 함께 떠납니다. 그들의 후임자는 코드는 물려받지만, 아무도 보관하지 않은 추론(reasoning)은 물려받지 못합니다. 버스 지수(Bus factor)는 결코 손(hands)에 관한 것이 아니었습니다. 그것은 머리(head)에 관한 것이었습니다.

신규 입사자는 결론만 읽을 수 있을 뿐, 과정을 재현할 수는 없습니다. 전체 세션(Full session)이 있으면 어떤 결과물이 나왔는지뿐만 아니라, 그 결과가 어떻게 도출되었는지 과정을 볼 수 있습니다.

의사결정 고고학 (Decision archaeology)을 수행할 곳이 없습니다. 6개월 뒤 누군가 "왜 이걸 이런 방식으로 만들었나요?"라고 물었을 때, 그 답은 원래의 기록에 있거나 아무도 기억하지 못하는 회의 속에 있습니다. 현재로서는 후자(회의)입니다.

그리고 가장 중요한 부분은 이것입니다. 이 기록을 유지하는 데 추가적인 작업 비용이 전혀 들지 않는다는 점입니다.

지식 베이스 (Knowledge bases)는 항상 한 가지 이유로 실패했습니다. 가장 바쁜 사람에게 문서를 작성할 시간을 내라고 요구했기 때문입니다. 이번에는 다릅니다. 최고의 기록은 사람들이 그저 자신의 업무를 수행할 때 발생하는 부산물입니다. 여러분이 해야 할 유일한 일은 그 기록을 삭제하는 것을 멈추는 것뿐입니다.

나머지는 엔지니어링 문제입니다. 팀의 세션을 어떻게 유지하고, 한곳에 모으고, 검색 가능하게 만들 것인가 하는 문제입니다. 방법은 다음과 같습니다. 혼자서 먼저 시도해 보는 데는 약 5분 정도 걸립니다.

완료 시 얻게 되는 것

• 로컬 AI 세션을 자동으로 수집하여, 민감 정보를 제거(redacted)하고 전체 트랜스크립트 (transcripts)로 저장하는 git 리포지토리 (git repo)
• MCP를 통해 Claude Code에서 일상적인 영어로 팀의 이력을 질문할 수 있는 능력
• 복사해서 바로 실행할 수 있는 일련의 명령어 세트 (로컬에서 약 5분 내에 작동)
• "혼자 시도하기"에서 "팀 전체가 공유하기"로 나아가는 경로
• 언제 가치가 있고 언제 가치가 없는지, 그리고 데이터가 어디에 있는지에 대한 명확한 이해

이 도구는 Klear-Team-Brain이라는 이름의 오픈 소스이며, Apache-2.0 라이선스를 따릅니다. 완성된 모습을 먼저 보고 싶으신가요? 리포지토리의 README에 여러분이 곧 실행하게 될 것과 동일한 명령어들이 있습니다.

필요한 사항

Node 22+ 버전과 MCP 지원 에디터(editor) 또는 CLI가 필요합니다. Claude Code, Codex, Cursor, Cline, Gemini CLI 모두 동일한 방식으로 작동합니다.

또한 캡처할 기존의 Claude Code / Codex 세션이 필요합니다. 두 도구를 조금이라도 사용해 보았다면, 이미 ~/.claude와 ~/.codex에 저장되어 있을 것입니다.

그 외에는 터미널만 있으면 됩니다. 데이터베이스도, 원하지 않는 한 Docker도, 클라우드 계정도 필요 없습니다.

이 기록을 수동으로 모으는 것이 비참한 이유

도구를 찾기 전에, 이를 수동으로 수행하는 모습을 상상해 보세요.

여러분의 세션은 ~/.claude 및 ~/.codex 내에 대화당 하나의 파일인 JSONL 파일로 존재합니다. 한 번이라도 열어본 적이 있다면 그 상태가 어떠한지 알 것입니다. 가공되지 않은 도구 호출 (tool calls), base64 이미지, 거대한 붙여넣기 블록(pasted blobs) 등이 모두 뒤섞여 있습니다.

이를 사용 가능한 상태로 만들려면 관련 있는 것들을 골라내고, 언젠가 분명히 붙여넣었을 비밀 정보(우리 모두가 해본 일입니다)를 삭제(scrub)한 뒤, 각각을 읽을 수 있는 형태로 압축해야 합니다.

게다가 이것은 단지 당신의 것일 뿐입니다. 팀 전체가 혜택을 보려면 모든 사람의 데이터를 모은 다음, 그 전체를 검색할 수 있는 방법을 구축해야 합니다.

팀 전체를 위해 이 작업을 수동으로, 영원히 반복해야 합니다. 아무도 이렇게 하지 않습니다. 이것이 바로 최고의 기록이 개별 기기에서 썩어가고 있는 이유입니다.

저도 한때 제 기록만이라도 수동으로 관리해 보려 했습니다. 각 트랜스크립트(transcript)에서 붙여넣은 비밀 정보를 삭제하는 것만으로도 포기하기에 충분했습니다.

이후의 내용은 이 과정을 자동화하고, 그 결과물을 평문(plain language)으로 쿼리할 수 있게 만드는 방법을 다룹니다.

• 수동 방식: 세션 찾기, 비밀 정보 삭제, 읽기 가능하게 압축, 모두의 데이터 수집, 검색 기능 구축, 이 과정을 영원히 반복
• 이 도구 사용 시: 백그라운드 수집기(background collector)가 캡처 및 비식별화(redacts) 수행; 결과물은 에디터에서 즉시 검색 가능한 git 리포지토리(repo)로 저장; 영어로 질문 가능

이제 만들어 봅시다.

1. 클론(Clone)하고, 로컬 ID 생성하기

먼저 여러분의 개인 기기에서 단독으로 실행해 보겠습니다. 이것이 결과를 확인하는 가장 빠른 방법이며, 노트북 외부로 나가는 데이터는 아무것도 없습니다.

git clone https://github.com/Asklear/Klear-Team-Brain.git && cd Klear-Team-Brain
npm install
npm run quickstart

quickstart는 일회성 작업입니다. 로컬 ID와 토큰을 생성하고, 클라이언트를 localhost로 지정하며, 여러분을 위해 MCP를 연결합니다. MCP가 무엇인지는 4단계에서 설명합니다.

2. 진실 저장소(truth store) 시작하기

"진실 저장소(truth store)"는 세션을 보관하는 git 리포지토리입니다. 서버를 시작하고 계속 실행 상태로 두세요:

npm run server   # http://127.0.0.1:8787 에서 서비스됩니다 — 이 터미널을 열어두세요

이것이 백엔드의 전부입니다: 하나의 git 리포지토리, 하나의 Node 프로세스, 그리고 정적 프론트엔드(static frontend). 데이터베이스도, 큐(queue)도, 벡터 스토어(vector store)도 없습니다.

쿼리는 git grep에서 실행되므로, 서버는 단 한 번도 LLM (Large Language Model)을 호출하지 않습니다. 이해(understanding)는 이곳이 아니라 여러분의 에디터 안에 있는 에이전트(agent) 내에서 일어납니다.

정상 작동을 확인하려면 http://127.0.0.1:8787/을 여세요. 대시보드가 나타날 것입니다. 지금은 비어 있습니다.

3. 세션 캡처하기 (Capture your sessions)

두 번째 터미널을 열고 (첫 번째 터미널에서는 서버를 계속 실행 상태로 두세요), 로컬 머신의 AI 세션들을 가져옵니다:

npm run sync -- --once

이 명령은 ~/.claude / ~/.codex 히스토리를 탐색하며, 각 세션을 압축(inline images 제거, 너무 큰 도구 출력값은 잘라내기, 바이트가 아닌 시그널 단위로 처리)하고, 데이터가 기록되기 전에 클라이언트 측에서 비밀 정보(secrets)와 홈 디렉토리 경로를 제거한 뒤, 각 세션을 진실 저장소(truth store)에 커밋(commit)합니다.

--once 옵션을 빼고 npm run sync를 실행하면 상주(resident) 상태로 유지되며, 새로운 세션이 생성될 때마다 이를 캡처합니다.

대시보드를 새로고침하세요. 이제 세션 목록이 표시될 것입니다.

4. MCP 단계가 실제로 연결한 것

1단계에서 quickstart는 MCP를 통해 진실 저장소를 Claude Code에 조용히 연결했습니다. MCP를 AI 앱을 위한 USB-C 포트라고 생각하세요. 즉, 에이전트가 외부 도구에 연결되는 표준화된 방식입니다. 여기서 도구는 여러분의 진실 저장소입니다.

제 말만 믿지 마시고 직접 확인해 보세요:

claude mcp list

team-brain이 목록에 있고 연결된 것을 볼 수 있을 것입니다.

다른 에디터(Codex, Cursor 등)를 연결하려면, MCP 서버는 일반적인 stdio 바이너리입니다. brain mcp를 실행하면 여러분의 머신에 맞는 정확한 명령어가 출력되며, 다음과 같은 형태일 것입니다:

# 이것은 quickstart가 등록한 내용입니다. 다른 MCP 클라이언트에 추가할 수 있도록 보여줍니다.
claude mcp add team-brain --scope user -- node /absolute/path/to/Klear-Team-Brain/mcp/server.mjs

brain mcp가 제공하는 절대 경로를 사용하고, 추가한 후에는 에디터를 재시작하세요.

5. 평범한 영어로 질문하기

이제 재미있는 부분입니다. Claude Code에서 그냥 물어보세요. 특별한 구문은 필요 없습니다:

Where did I leave the auth refactor, and what was still unresolved?
(인증 리팩토링을 어디까지 진행했었지? 그리고 아직 해결되지 않은 문제는 뭐였지?)

에이전트는 진실 저장소를 읽기 전용(read-only) 폴더로 취급하며, 몇 가지 유닉스 스타일(Unix-style) 도구를 사용하여 이를 파헤칩니다:

도구 (Tool)	기능
grep	git grep을 통해 세션 전반에 걸친 정규 표현식 (regex) 전체 텍스트 검색
...

따라서 당신의 한 줄짜리 질문은 "auth"를 grep으로 찾고, 검색된 세션들을 read한 다음, 이를 종합(synthesize)하는 과정이 됩니다.

답변은 인용된 특정 세션들과, 커밋 메시지(commit message)에는 포함되지 않았던 막다른 길(dead ends) 및 판단 근거(judgment calls)들을 언급합니다.

정말로 변한 것은 팀이 일하는 방식입니다. 보통 다음의 질문들은 적절한 사람을 찾아 그들이 기억하기를 바라고, 그들의 업무 시간 중 30분을 할애해야 함을 의미합니다:

이번 주에 ETL 코드를 건드린 사람이 누구죠?
결제 스키마(billing schema)를 어떻게 결정했나요? 그리고 무엇을 거절했었죠?

이제 이 질문들은 하나의 쿼리(query)가 되었습니다.

내부적으로 어떤 일이 일어나고 있는가, 그리고 왜 내가 팀 데이터를 이에 맡기는가

이 부분은 정확하게 짚고 넘어갈 가치가 있습니다. 왜냐하면 이 부분이 당신이 팀의 작업물을 이 시스템에 넘겨줄지 여부를 결정하는 핵심이기 때문입니다.

이 시스템은 읽기 전용(read-only)입니다. 모든 서버 측 쿼리는 execFile을 통해 쉘(shell) 없이, 진실 저장소(truth-store) 디렉토리 내에 잠긴 상태로 git grep, git ls-files, git log 또는 일반 파일 읽기를 수행합니다. 도구들은 읽을 수는 있지만, 쓸 수는 없으며, 임의의 명령(arbitrary commands)을 실행할 수도 없습니다.

서버는 모델을 단 한 번도 호출하지 않습니다. 서버는 단지 에디터(editor)에 있는 에이전트(agent)에게 텍스트를 전달할 뿐이며, 추론(reasoning)은 에이전트가 수행합니다. 이것이 나중에 아주 작은 VPS에서도 잘 작동하는 이유입니다. 무거운 작업은 서버가 하고 있지 않기 때문입니다.

데이터는 git 저장소(repo)입니다. 당신은 그 안으로 cd하여 일반적인 도구들로 모든 것을 읽을 수 있습니다. 독점적인 형식(proprietary format)도 없고, 종속(lock-in)도 없습니다. 만약 당신이 내일 떠나더라도, 팀의 사고 과정이 담긴 깨끗하고 익명화된(redacted) 기록을 여전히 보유하게 됩니다.

이 시스템이 하지 않는 것, 그리고 사용하지 않아도 되는 경우

솔직하게 말씀드리겠습니다.

이것은 챗봇(chatbot)도 아니고 프로젝트 매니저(project manager)도 아닙니다. 이것은 팀의 세션, 코드, 문서를 집계하여 당신이 이를 이해하도록 돕는 도구입니다. 업무를 할당하지 않으며, Slack을 대체하지도 않습니다.

만약 당신이 혼자 일하고 기억력이 좋다면, 아마 이것이 필요하지 않을 것입니다. 이 시스템의 가치는 1인 주말 프로젝트가 아니라, 팀의 규모와 시간에 비례하여 커집니다.

그리고 이것은 여러분의 업무 전체가 아니라 AI 세션(AI sessions)을 캡처합니다. 머릿속으로 했던 추론이나 회의에서 결정된 사항은 여기에 포함되지 않습니다. 그렇기는 하지만, AI에게 입력하는 공유 데이터는 계속해서 늘어나고 있으며, 이것이 바로 이 도구의 핵심 목적입니다.

데이터에 대해 명확히 말씀드리자면, 여러분이 명시적으로 허용 목록(allowlist)에 추가한 디렉터리만 업로드됩니다. 비밀 정보(Secrets)는 기기를 떠나기 전 클라이언트 측에서 마스킹(redacted) 처리됩니다. brain viewer를 실행하여 각 세션별로 정확히 무엇이 캡처되었는지 확인하고, 공유를 원하지 않는 것은 무엇이든 철회할 수 있습니다.

전체 시스템은 셀프 호스팅(self-hosted) 방식이므로, 팀에 도입하더라도 여러분의 그룹만이 접근할 수 있는 인프라 내에서 작동합니다. 만약 팀의 세션이 민감한 데이터에 접근한다면, "읽기 전용, 셀프 호스팅, 소스 단계에서의 마스킹(read-only, self-hosted, redacted at the source)"이라는 점이 가장 중요하게 작용할 것입니다.

혼자 시도하는 것에서 팀 전체로

위에서 설명한 개인용 실행은 한 사람에게 맞춰진 실제 사례입니다.

이를 공유 메모리(shared memory)로 전환하려면, 하나의 작은 VPS(저사양 메모리도 괜찮습니다)에 동일한 서버를 구축하고, 각 팀원이 자신의 클라이언트를 해당 서버로 연결하면 됩니다:

curl -fsSL https://your-server.example.com/get | bash   # 클라이언트 + `brain` 명령어 설치
brain join <YOUR_INVITE_TOKEN>                           # 인증, 워크스페이스 선택, MCP 연결, 첫 동기화

그 이후에는 수집기(collector)가 백그라운드에서 실행되며 모든 팀원의 세션이 자동으로 흘러 들어옵니다. 실무를 수행하는 사람들은 아무것도 할 필요가 없지만, 그들의 추론 과정은 여전히 공유 메모리에 기록됩니다. 이해하고 싶은 사람들은 그저 질문하기만 하면 됩니다.

전체 서버 설정(TRUTH_DIR, 명부(roster), 토큰, HTTPS, 서비스로 실행, Docker)은 리포지토리의 DEPLOY.md에 있습니다.

만약 이것이 여러분의 문제이기도 하다면, 리포지토리는 여기에 있습니다: https://github.com/Asklear/Klear-Team-Brain. 스타(star)를 눌러주시는 것은 동일한 문제를 가진 다음 팀에게 이 도구가 전달되는 데 진심으로 큰 도움이 됩니다. 그리고 사용해 보시다가 어려운 점이 있다면, 이슈(issue)를 남겨주시는 것이 저에게 더 큰 도움이 됩니다.