AlmanacCode/codealmanac

무엇을 해결하는가

CodeAlmanac은 코드만으로는 아키텍처 결정의 근거, 과거의 실패 사례, 시스템 불변성 또는 복잡한 서비스 간 워크플로우를 설명할 수 없는 소프트웨어 개발의 "context gap"을 해결합니다. 이는 커밋 메시지에서 누락되거나 문서 곳곳에 흩어져 있는 고수준의 컨텍스트를 캡처하여 "living wiki"를 유지하는 방법을 제공합니다.

어떻게 작동하는가

이 도구는 저장소의 almanac/ 디렉토리 아래에 직접 저장되는 일반 Markdown 파일로 구성된 위키를 생성합니다. AI 코딩 에이전트(Codex 또는 Claude Code를 통해)를 사용하여 다음 세 가지 주요 프로세스를 통해 이 위키를 자동으로 유지 관리합니다:

• Ingestion: AI 에이전트가 파일, Git diffs, PRs, issues, 그리고 에이전트 트랜스크립트를 스캔하여 새로운 지식을 위키에 통합합니다.
• Gardening: 오래된 페이지를 정리하고, 깨진 링크를 수정하며, 중복된 정보를 제거하는 주기적인 AI 기반 리뷰입니다.
• Syncing: 최근 AI 에이전트 대화 내용을 스캔하여 위키를 위한 유용한 지식을 추출하고 대기열에 추가하는 백그라운드 프로세스입니다.

사용자는 CLI를 통해 페이지를 검색하고 볼 수 있거나, 로컬 웹 뷰어를 통해 위키와 상호작용할 수 있습니다.

누구를 위한 것인가

AI 에이전트에 의해 자동으로 업데이트되고 표준 Git 워크플로우를 통해 리뷰되는 최신 프로젝트 문서를 유지 관리하고자 하는 개발자와 팀입니다.

주요 특징

• Git-native: 위키는 저장소에 Markdown 형식으로 저장되므로, 변경 사항은 pull requests를 통해 리뷰됩니다.
• Automated Maintenance: macOS의 백그라운드 launchd 작업을 사용하여 수동 작업 없이 위키를 동기화하고 "garden"합니다.
• Agent-Integrated: Codex 및 Claude Code와 직접 통합되어 대화 트랜스크립트를 영구적인 문서로 변환합니다.
• Local-first: 모든 위키 작업과 인덱싱은 사용자의 로컬 머신에서 수행됩니다.
• Web Viewer: 위키 그래프를 탐색할 수 있는 읽기 전용 로컬 웹 인터페이스를 포함합니다.