🤖 Local AI Documentation Agent

"코드는 변하는데 문서는 그대로인가요?"

로컬 Git 변경 사항을 감지하여 프로젝트 문서(README.md, /docs/*.md)를 자동으로 최신화해주는 Self-hosted AI 에이전트입니다.

📖 프로젝트 개요 (Overview)

TDD(Test Driven Development)와 DDD(Domain Driven Design)를 실천하다 보면 구현 코드와 요구사항 문서(requirements.md, tests.md) 간의 동기화가 깨지는 문제가 빈번하게 발생합니다.

이 프로젝트는 개발자가 문서 작성이라는 '컨텍스트 스위칭' 비용을 줄이고 본질적인 로직 구현에 집중할 수 있도록 돕는 로컬 자동화 파이프라인입니다. 외부 Git Provider(Github Actions 등)에 의존하지 않고, 로컬 Docker 환경에서 안전하고 빠르게 동작합니다.

🚀 핵심 기능 (Key Features)

• 🔒 보안 중심 (Privacy First): 소스 코드를 외부 서버에 업로드하지 않고, Docker Volume Binding을 통해 로컬에서 직접 파일을 읽고 씁니다.
• ⚡️ 토큰 효율화 (Token Efficiency): 전체 코드가 아닌 git diff를 분석하여 변경된 로직과 관련된 문서만 선별적으로 업데이트합니다.
• 🤖 AI 기반 문서 작성: Google Gemini 2.5 Pro 모델을 활용하여 기술적 정확도가 높은 문서를 생성합니다.
• 📢 실시간 알림: 작업 완료 시 Discord Webhook을 통해 변경된 파일 내역을 Embed 카드 형태로 즉시 받아봅니다.
• 🛠 원 클릭 실행: Git Alias(git docs)를 통해 커밋 직후 터미널 흐름을 끊지 않고 에이전트를 호출합니다.

---

🏗️ 아키텍처 (Architecture)

graph LR
    User((Developer)) -->|git commit & git docs| LocalShell[Local Shell]
    LocalShell -->|Webhook Trigger| n8n[n8n Container]

    subgraph "Dockerized Agent (n8n)"
        n8n -->|1. Execute Command| Git[Git Diff Analysis]
        Git -->|2. Read Changes| FileSystem[(Local Project Volume)]
        FileSystem -->|3. Context Loading| LLM[Gemini 2.5 Pro]
        LLM -->|4. Generate JSON| Parser[JSON Parser]
        Parser -->|5. Update Files| FileSystem
    end

    Parser -->|6. Notify| Discord[Discord Webhook]
    Discord -->|Alert| User

Loading

---

🛠️ 기술 스택 (Tech Stack)

• Orchestration: n8n (Self-hosted via Docker)
• LLM: Google Gemini 2.5 Pro (via PaLM API)
• Infrastructure: Docker & Docker Compose
• Version Control: Git (Local Repository)
• Notification: Discord Webhook API

---

⚙️ 설치 및 실행 방법 (Installation)

1. 사전 준비 (Prerequisites)

• Docker & Docker Compose
• Google Gemini API Key
• Discord Webhook URL
• .env 의 소스코드 루트 경로 업데이트

2. 환경 구성 (Docker Compose)

프로젝트 루트에 docker-compose.yml 파일을 생성하고, 로컬 프로젝트 경로를 볼륨으로 마운트합니다.

version: "3.8"

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n-local-docs-agent
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - WEBHOOK_URL=http://localhost:5678/
      - GENERIC_TIMEZONE=Asia/Seoul
    user: root # 로컬 파일 쓰기 권한 확보
    volumes:
      - n8n_data:/home/node/.n8n
      # [중요] 내 로컬 프로젝트 경로를 컨테이너 내부로 마운트
      - ./my-project:/data/projects
    command: /bin/sh -c "git config --global --add safe.directory /data/projects && n8n start"

volumes:
  n8n_data:

3. 워크플로우 가져오기 (Import Workflow)

1. n8n (http://localhost:5678) 접속
2. Workflows > Import from File 또는 Import from URL
3. 본 레포지토리에 포함된 workflow.json 파일을 업로드합니다.
4. Credentials 설정:
   • Google Gemini(PaLM) Api account: API Key 입력
   • Discord Webhook account: Webhook URL 입력

4. Git Alias 설정 (Optional)

터미널에서 간편하게 호출하기 위해 Alias를 등록합니다. (WEBHOOK_URL은 n8n의 Production URL 사용)

git config --global alias.docs "!curl -X POST -s -o /dev/null http://localhost:5678/webhook/YOUR-UUID && echo '✅ 문서화 에이전트 실행 완료!'"

---

💻 사용 예시 (Usage)

기능 구현 후 터미널에서 아래와 같이 실행합니다.

# 1. 코드 변경 사항 커밋
$ git add .
$ git commit -m "feat: 로또 번호 생성 로직 구현"

# 2. 문서화 에이전트 호출
$ git docs
✅ 문서화 에이전트 실행 완료!

잠시 후 Discord로 알림이 도착하며, README.md와 docs/*.md 파일이 자동으로 업데이트됩니다.

---

📂 워크플로우 상세 로직

1. Webhook Trigger: 로컬 쉘에서 POST 요청을 수신합니다.
2. Diff Checker: git diff main...HEAD 명령어로 main 브랜치와 비교되는 최근 작업 내역만 추출합니다.
3. Context Loader: README.md 및 docs/ 하위의 모든 마크다운 파일을 읽어옵니다.
4. LLM Processing: Gemini Pro에게 "테크니컬 라이터" 페르소나를 부여하여 문서를 작성합니다.
   • Output Format: JSON Array (fileName, content)
5. Dynamic File Write: 파싱된 JSON을 순회하며 변경된 파일만 로컬 디스크에 덮어씁니다.
6. Notification: 작업 결과를 Discord Embed 메시지로 전송합니다.

---

📝 License

This project is licensed under the MIT License.

---