SethDrew/project-ledger

project-ledger은(는) 무엇을 하나요?

AI 기반 개발을 위한 구조화된 파인딩 시스템입니다. YAML 원장 + Claude Code 스킬 + TF-IDF 컨텍스트 주입 훅을 제공합니다.

개요

project-ledger는 AI 어시스턴트가 프로젝트의 진행 상황과 이전 작업 맥락을 지속적으로 추적할 수 있도록 설계된 시스템입니다. YAML 형식으로 작성된 원장 파일을 사용하며, Claude Code의 스킬 메커니즘과 TF-IDF 기반 컨텍스트 검색을 결합하여 관련 정보를 자동으로 주입합니다.

주요 기능

• 구조화된 원장: YAML 형식으로 작업 내역, 결정 사항, 이슈, 참고 자료를 체계적으로 기록
• Claude Code 통합: 스킬로 설치하여 Claude Code 세션에서 자동으로 원장 참조
• TF-IDF 컨텍스트 주입: 가장 관련성 높은 원장 항목을 자동으로 검색하여 AI 프롬프트에 포함

설치 방법

Claude Code 스킬로 설치

# 스킬 디렉토리로 이동
cd ~/.claude/skills/

# 저장소 클론
gh repo clone SethDrew/project-ledger

또는 수동으로 SKILL.md 파일과 관련 스크립트를 복사하십시오.

사용 방법

1. 원장 초기화

프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 원장 파일을 생성합니다:

touch ledger.yaml

2. 항목 추가

ledger.yaml 파일에 다음 형식으로 항목을 추가합니다:

- date: 2024-01-15
  type: decision
  title: 데이터베이스 스키마 설계
  description: PostgreSQL 기반으로 스키마를 설계하기로 결정
  rationale: 관계형 데이터의 복잡한 질의가 필요함
  tags: [database, schema, postgresql]

- date: 2024-01-16
  type: issue
  title: 사용자 인증 토큰 만료 문제
  description: JWT 토큰이 1시간 후 만료되어 사용자 세션이 끊김
  resolution: 토큰 갱신(refresh token) 메커니즘 추가 예정
  tags: [auth, jwt, security]

3. TF-IDF 컨텍스트 주입

제공된 Python 스크립트를 사용하여 현재 작업과 관련된 원장 항목을 자동으로 추출합니다:

python3 inject_context.py ledger.yaml "현재 작업 설명"

이 명령은 TF-IDF 유사도 점수를 기반으로 가장 관련성 높은 항목 5개를 선택하여 출력합니다.

원장 항목 유형

유형	설명	필수 필드
decision	프로젝트 결정 사항	date, title, description, rationale
issue	발견된 문제 또는 장애물	date, title, description, resolution
task	완료된 작업 내역	date, title, description
reference	유용한 참고 자료	date, title, url 또는 source

컨텍스트 주입 스크립트

inject_context.py 스크립트는 Python 3와 scikit-learn 라이브러리가 필요합니다:

pip install scikit-learn pyyaml

스크립트 사용법

# inject_context.py 예제
from sklearn.feature_extraction.text import TfidfVectorizer
import yaml
import sys

def load_ledger(path):
    with open(path, 'r') as f:
        return yaml.safe_load(f)

def inject_context(ledger_path, query):
    ledger = load_ledger(ledger_path)
    descriptions = [item['description'] for item in ledger]
    vectorizer = TfidfVectorizer()
    tfidf_matrix = vectorizer.fit_transform(descriptions + [query])
    # 유사도 계산 로직
    # ...

환경 변수

• LEDGER_PATH: 원장 파일 경로 (기본값: ./ledger.yaml)
• CONTEXT_COUNT: 주입할 컨텍스트 항목 수 (기본값: 5)

라이선스

MIT

기여

이슈와 풀 리퀘스트를 환영합니다. 주요 변경 사항은 먼저 이슈를 열어 논의해 주십시오.