PAELLADOC

🧠 PAELLADOC: AI 우선 개발 프레임워크

공식 웹사이트를 방문하세요

버전 0.3.7 : v0.3.6 빌드에서 실수로 누락되었던 핵심 프로젝트 CRUD 도구를 복원하는 핫픽스 릴리스입니다. 자세한 내용은 변경 로그를 확인하세요!

"AI 시대에는 컨텍스트가 코드를 보완하는 것이 아니라 가장 중요한 창조물입니다."

PAELLADOC은 AI 우선 개발 의 5가지 철학적 원칙을 구현한 AI 우선 개발 프레임워크로, AI 시대에 소프트웨어를 만드는 방식을 혁신합니다.

🎯 PAELLADOC 및 모델 컨텍스트 프로토콜(MCP)

PAELLADOC은 Anthropic의 모델 컨텍스트 프로토콜(MCP)을 구현합니다( Anthropic 뉴스 참조 ). 이 프로토콜은 대규모 언어 모델(LLM)이 외부 도구 및 컨텍스트와 상호 작용할 수 있는 구조화된 방식을 제공하여 더욱 정교한 기능을 구현할 수 있도록 합니다.

PAELLADOC은 MCP를 구현함으로써 LLM이 이 표준을 통해 PAELLADOC의 특정 AI-First 개발 도구와 워크플로를 직접 활용할 수 있도록 지원합니다. 이러한 접근 방식은 다른 플랫폼에서 볼 수 있는 도구 사용 이나 함수 호출 과 유사한 기능을 제공하지만, 상호작용에는 Anthropic MCP 표준을 특별히 활용합니다.

🎯 AI 우선 철학

기존 개발 방식은 문서화를 부차적인 문제로 여겼습니다. AI 우선 개발은 이러한 패러다임을 뒤집습니다.

• 컨텍스트가 주요 아티팩트가 됩니다.
• 코드는 그것의 표현이 됩니다
• 지식은 시스템과 함께 발전합니다
• 결정은 철학적 맥락을 보존합니다.
• 인간과 AI의 협업이 원활합니다

🧠 실천하는 5가지 원칙

1. 맥락이 주요 창조물

지엑스피1

• 모든 아티팩트에는 완벽한 추적을 위한 UUID가 있습니다.
• 컨텍스트는 코드와 함께 버전이 지정됩니다.
• 지식 그래프는 관계를 포착합니다.
• 의도는 모든 단계에서 보존됩니다.

2. 의도 기반 아키텍처

• 아키텍처는 구현이 아닌 의도에서 흐릅니다.
• 모든 결정은 철학적 맥락을 포착합니다.
• 시스템은 변화하는 목적에 적응합니다

3. 살아있는 실체로서의 지식

• 프로젝트 메모리는 이해의 진화를 추적합니다.
• 변경 사항이 있을 경우 문서가 자동으로 업데이트됩니다.
• 맥락은 새롭고 관련성이 유지됩니다.
• 지식 그래프는 관계를 보여줍니다.

4. 인간-AI 협력 의식

• 자연어 대화
• 의도 보존
• 상황 인식
• 원활한 협업

5. 상황적 의사결정 아키텍처

• 모든 결정은 그 맥락을 유지합니다
• 미래의 개발자들은 "이유"를 이해합니다.
• 변경 사항은 역사적 맥락을 존중합니다.
• 의도는 여전히 명확하다

🚀 설치 및 통합

PAELLADOC은 Python 애플리케이션이므로 전용 Python 가상 환경 에 설치해야 합니다. 이렇게 하면 종속성이 분리되어 충돌을 방지할 수 있습니다. 문서화하려는 프로젝트(Python, JS, Ruby 등)의 수에 관계없이 하나의 PAELLADOC 환경이 필요합니다.

(Python 3.12 이상 필요)

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 PAELLADOC을 자동으로 설치하려면:

1. 전용 환경 생성 및 활성화

먼저, 이 환경에 대한 영구적인 위치를 선택하세요. 홈 디렉터리가 좋은 선택이 될 수 있습니다.

(이제 터미널 프롬프트 시작 부분에 (.paelladoc_venv) 가 표시되어야 합니다.)

2. 활성화된 환경에 PAELLADOC 설치

3. 데이터베이스 경로 구성

PAELLADOC은 메모리 데이터베이스( memory.db )를 어디에 저장할지 알아야 합니다. 이를 구성하는 두 가지 주요 방법은 다음과 같습니다.

옵션 1: 환경 변수(LLM 통합에 대한 안정성 낮음)

PAELLADOC_DB_PATH 환경 변수를 설정할 수 있습니다. 터미널에서 PAELLADOC을 직접 실행하면 이 설정이 효과적입니다.

중요: PAELLADOC이 LLM 도구(예: MCP를 통한 Cursor)로 실행되는 경우, 이 방법으로 설정된 환경 변수를 상속하지 않을 수 있습니다. 따라서 이 방법은 LLM 통합에 덜 안정적 입니다.

옵션 2: MCP 구성(LLM 통합에 권장)

LLM 도구가 올바른 데이터베이스 경로를 사용하는지 확인하는 가장 확실한 방법은 도구의 MCP JSON 파일(Cursor의 경우 .cursor/mcp.json )에서 직접 구성하는 것입니다. 이렇게 하면 LLM이 시작한 서버 프로세스에 변수가 직접 삽입됩니다.

다음 섹션의 예를 참조하세요.

4. LLM 구성(MCP 설정)

이제 LLM 도구(예: Cursor)에 PAELLADOC을 찾아 실행하는 방법을 알려주세요.

필요한 주요 정보:

• Python 실행 파일의 전체 경로: .paelladoc_venv 내부의 python 에 대한 절대 경로입니다.

커서 IDE 예제

.cursor/mcp.json 파일을 편집하세요. PAELLADOC에 대한 서버 구성을 추가하세요. 일반적인 예는 다음과 같습니다.

중요 참고 사항:

• command 경로는 .paelladoc_venv 파일(1단계에서 생성)에 있는 Python 실행 파일의 절대 경로 여야 합니다 . /absolute/path/to/ 시스템의 실제 경로(예: /Users/your_username/ )로 바꾸세요.
• 데이터베이스 경로:
  • 기본적으로( env 에 PAELLADOC_DB_PATH 설정되지 않은 경우) PAELLADOC은 ~/.paelladoc/memory.db 사용합니다.
  • 프로젝트 코드와 함께 데이터베이스가 필요한 로컬 개발의 경우, 예시처럼 env 섹션에 PAELLADOC_DB_PATH 설정하는 것이 권장되고 가장 안정적인 방법입니다. /path/to/your/project/directory/ 실제 프로젝트 경로로 바꾸세요.
• 작업 디렉토리( cwd ): 이것을 프로젝트 디렉토리로 설정하면 도움이 될 수 있지만 종종 선택 사항입니다.
• PYTHONPATH: PAELLADOC 자체에서 로컬 개발을 수행하고 서버에서 소스 코드를 찾아야 하는 경우 env 에 이것을 설정하는 것이 필요할 수 있습니다.

4. LLM이 당신을 안내하게 하세요

연결되면 LLM은 모든 PAELLADOC 명령에 액세스할 수 있습니다.

• PAELLA : 새로운 문서화 프로젝트 시작
• CONTINUE : 기존 문서 계속
• VERIFY : 문서 범위 확인
• GENERATE : 문서 또는 코드 생성

LLM은 모든 복잡한 문제를 처리해 주므로, 여러분은 자연어로 의도만 표현하면 됩니다!

🚦 버전 안정성

• PyPI 버전(안정적): PyPI에 게시된 버전( pip install paelladoc )은 일반적인 사용에 권장되는 안정적인 릴리스입니다.
• GitHub 저장소(개발): GitHub 저장소 의 main 브랜치(및 기타 브랜치)에는 최신 개발 코드가 포함되어 있습니다. 이 버전에는 아직 완전히 테스트되지 않아 불안정한 것으로 간주되는 새로운 기능이나 변경 사항이 포함될 수 있습니다. 최첨단 기능을 사용해 보거나 개발에 기여하려면 이 버전을 사용하세요.

현재 개발 관련 참고 사항: 현재 내부적으로는 중요한 신규 기능을 갖춘 MVP(최소 기능 패키지)를 제공하기 위한 개발이 활발하게 진행되고 있습니다. PyPI 버전은 안정적으로 유지되지만, 현재는 보다 비공개적인 환경에서 이 목표를 달성하기 위해 노력하고 있으므로 향후 릴리스에서 주요 개선 사항이 추가될 것으로 예상됩니다.

🚀 빠른 시작

1. PAELLADOC가 설치 ( pip install paelladoc )되었고 LLM 도구/MCP 설정에서 구성되어 있는지 확인하세요(위의 예 참조).
2. LLM을 통해 PAELLADOC과 소통하려면 명령어를 실행하세요 . 새 프로젝트를 시작하거나 기존 프로젝트를 나열하는 기본 명령어는 PAELLA 입니다.
   • 커서나 비슷한 채팅 인터페이스에서 다음을 입력하기만 하면 됩니다.
     PAELLA
   • 또는 LLM에 대해 더 명확하게 지시할 수 있습니다.
     Use PAELLADOC to start documenting a new project.
     Tell PAELLADOC I want to create documentation.
3. LLM의 안내를 따르세요. PAELLADOC(LLM을 통해)가 대화형으로 과정을 안내하며 프로젝트 세부 정보, 템플릿 선택 등을 묻습니다.

⚙️ 사용 가능한 명령(v0.3.7)

이 버전은 LLM과의 상호작용을 위해 MCP를 통해 제공되는 다음과 같은 핵심 명령을 제공합니다.

• ping :
  • 설명: 서버가 실행 중이고 응답하는지 확인하기 위한 기본 상태 점검입니다.
  • 인수: 없음(또는 선택적 random_string ).
  • 반환 값: { "status": "ok", "message": "pong" } .
• paella_init :
  • 설명: 새로운 PAELLADOC 프로젝트를 초기화하여 필요한 구조와 초기 메모리 파일을 만듭니다.
  • 인수: base_path (str), documentation_language (str, 예: "es-ES"), interaction_language (str, 예: "en-US"), new_project_name (str).
  • 반환: 프로젝트 생성 상태, 이름, 경로를 확인하는 사전입니다.
• paella_list :
  • 설명: 메모리 데이터베이스에서 발견된 모든 PAELLADOC 프로젝트의 이름을 나열합니다.
  • 인수: 없음.
  • 반환: 프로젝트 이름( projects ) 목록이 포함된 사전입니다.
• paella_select :
  • 설명: 작업할 기존 PAELLADOC 프로젝트를 선택합니다(메모리를 로드합니다).
  • 인수: project_name (str).
  • 반환: 프로젝트 선택과 기본 경로를 확인하는 사전입니다.
• core_continue :
  • 설명: 이전에 선택한 프로젝트의 작업을 계속하고, 해당 프로젝트의 메모리를 로드하고 다음 단계를 제안합니다(기본 구현).
  • 인수: project_name (str).
  • 반환: 프로젝트 상태와 제안된 다음 단계가 포함된 사전입니다.
• core_help :
  • 설명: 사용 가능한 명령에 대한 도움말 정보를 제공합니다(기본 스텁 구현).
  • 인수: 없음(미래: 특정 명령).
  • 반환: 플레이스홀더 성공 메시지.
• core_list_projects :
  • 설명: ( paella_list 와 중복될 가능성이 있음) 기존 PAELLADOC 프로젝트의 이름을 나열합니다.
  • 인수: db_path (str, 선택 사항, 테스트용).
  • 반환: 프로젝트 이름( projects ) 목록이 포함된 사전입니다.
• core_verification :
  • 설명: 문서 품질과 완전성을 확인합니다(기본 스텁 구현).
  • 인수: 없음.
  • 반환: 플레이스홀더 성공 메시지.

🗺️ 향후 로드맵 주요 내용

통합 로드맵을 기반으로 향후 버전에는 다음이 포함될 예정입니다.

• 전체 대화형 문서 생성 흐름( GENERATE-DOC ).
• 코드 분석 및 컨텍스트 생성( GENERATE_CONTEXT ).
• 문서에서 자동 코드 생성( code_generation ).
• 코딩 스타일 및 Git 워크플로 관리( styles.coding_styles , styles.git_workflows )
• 결정, 이슈, 성과에 대한 프로젝트 메모리 명령( DECISION , ISSUE , ACHIEVEMENT ).
• 그리고 MECE 분류법과 A2A 역량에 맞춰 더 ���은 기능을 제공합니다.

📊 MECE 문서 구조

AI-First 분류법은 완전한 컨텍스트 보존을 보장합니다.