Skip to content

TEMPLATE_README.md

Latest commit

 

History

History
287 lines (209 loc) · 9.18 KB

TEMPLATE_README.md

File metadata and controls

287 lines (209 loc) · 9.18 KB

Act Template

이 문서는 본 스캐폴드(템플릿)로 생성된 프로젝트를 빠르게 이해하고, 올바르게 사용하는 방법을 안내합니다.

  • 템플릿 이름: Backand (slug: backand, snake: backand)
  • 워크스페이스 구성: uv 멀티 패키지(workspace) – [tool.uv.workspace].members = ["casts/*"]
  • 그래프 레지스트리: langgraph.json의 graphs 키를 통해 그래프 엔트리 등록

템플릿 개요

  • LangGraph 기반의 모듈화/계층화된 그래프 구조를 제공합니다.
  • casts/ 디렉터리에 개별 Cast를 패키지로 관리합니다(pyproject.toml 포함).
  • 공통 베이스는 casts/base_node.py, casts/base_graph.py에서 가져옵니다.
  • 각 Cast는 modules/(에이전트/조건/미들웨어/모델/노드/프롬프트/상태/툴/유틸), graph.py로 구성됩니다.
  • 상태 관리는 분리된 스키마를 사용합니다: 입력용 InputState, 출력용 OutputState, 내부 처리용 State.

디렉터리 구조(요약)

backand/
├── casts/
│   ├── __init__.py
│   ├── base_node.py
│   ├── base_graph.py
│   └── chat/
│       ├── modules/
│       │   ├── __init__.py
│       │   ├── agents.py (선택)
│       │   ├── conditions.py (선택)
│       │   ├── middlewares.py (선택)
│       │   ├── models.py (선택)
│       │   ├── nodes.py (필수)
│       │   ├── prompts.py (선택)
│       │   ├── state.py (필수)
│       │   ├── tools.py (선택)
│       │   └── utils.py (선택)
│       ├── __init__.py
│       ├── graph.py
│       ├── pyproject.toml
│       └── README.md
├── tests/
│   ├── __init__.py
│   ├── cast_tests/
│   └── node_tests/
├── langgraph.json
├── pyproject.toml
└── README.md

설치 및 준비

시스템 요구사항

  • Python 3.11 이상
  • uv (의존성/실행/빌드)
  • ruff (코드 품질/포맷)

uv 설치(미설치 시)

pip install uv

의존성 설치

  • 전체 워크스페이스(모든 Cast 패키지) + 개발 의존성 설치
uv sync --all-packages
  • 특정 Cast 패키지 설치(워크스페이스 멤버명 사용)
# 예: chat 만 설치
uv sync --package chat

멤버명은 casts/<cast_name> 하위의 각 pyproject.toml의 [project].name과 일치합니다.

그래프 레지스트리(langgraph.json)

langgraph.json에서 노출할 그래프를 선언합니다. 기본 예시는 다음과 같습니다.

{
  "dependencies": ["."],
  "graphs": {
    "main": "./casts/graph.py:main_graph",
    "chat": "./casts/chat/graph.py:chat_graph"
  },
  "env": ".env"
}
  • 특정 Cast만 사용한다면 해당 Cast 키만 남겨도 됩니다.
  • .env 경로는 환경변수 파일을 가리킵니다(필요 시 수정).

개발 서버 실행(LangGraph CLI)

개발/디버깅을 위해 인메모리 서버를 실행합니다.

uv run langgraph dev
  • 크롬 이외 브라우저 사용 시(터널 모드):
uv run langgraph dev --tunnel

서버 실행 후 접속 URL

참고: 본 서버는 개발/테스트용 인메모리 서버입니다. 프로덕션은 LangGraph Cloud 사용을 권장합니다.

종료 방법: 터미널에서 Ctrl + C(Windows), Cmd + C(macOS)

입력/상태 관리

  • 각 Cast는 casts/chat/modules/state.py에서 세 가지 구분된 상태 스키마를 사용합니다:
    • InputState: 그래프 호출을 위한 입력 스키마 정의
    • OutputState: 그래프가 반환하는 출력 스키마 정의
    • State: 메인 상태 컨테이너 (메시지 처리를 위해 MessagesState를 상속)
  • 실행 시 Studio UI 좌측 패널에 표시되는 입력 필드에 값을 지정한 뒤 Invoke 하십시오.
  • 그래프는 자동으로 InputState에 대해 입력을 검증하고 OutputState에 따라 출력 형식을 지정합니다.

새 Cast 추가

새로운 그래프/기능을 별도 Cast로 추가하려면 act cast 명령을 사용합니다. Act Operator는 이미 dev 의존성 그룹에 포함되어 있습니다.

# 의존성이 설치되어 있는지 확인
uv sync --all-packages

# 새 Cast 추가 (대화형 모드)
uv run act cast

# 또는 Cast 이름을 직접 지정
uv run act cast my-new-cast

# 또는 전체 옵션과 함께
uv run act cast --path . --cast-name "새 Cast 이름"

수행 내용:

  • Act 프로젝트 구조 검증
  • 필수 파일이 포함된 완전한 Cast 디렉터리 생성
  • langgraph.json 자동 업데이트
  • Cast를 workspace member로 구성

Cast 생성 후:

# 모든 패키지 설치 (새 Cast 포함)
uv sync --all-packages

Claude Skills

이 프로젝트는 개발을 지원하기 위해 .claude/skills/에 사전 구성된 Claude 스킬을 포함하고 있습니다. Claude Code나 Cursor에서 @skill-name 구문을 사용하여 호출할 수 있습니다.

사용 가능한 스킬

스킬 목적 사용 시점
@architecting-act 아키텍처 설계 새 cast 계획, 구조 불명확, CLAUDE.md 필요 시
@engineering-act 프로젝트 설정 cast 패키지 생성, 의존성 추가, 환경 동기화
@developing-cast 코드 구현 노드/에이전트/툴 구현, LangGraph 패턴 필요 시
@testing-cast 테스트 작성 pytest 테스트 생성, 모킹 전략, 픽스처

사용 방법

  1. 스킬 호출: 프롬프트에 @skill-name을 입력합니다

    @architecting-act RAG 파이프라인 설계를 도와줘
@developing-cast CLAUDE.md의 SearchNode를 구현해줘
@engineering-act 이 cast에 langchain-openai를 추가해줘
@testing-cast MyNode에 대한 테스트를 작성해줘

  2. 스킬 워크플로우: 각 스킬은 해당 도메인에 맞게 안내합니다

    • architecting-act: 대화형 Q&A → CLAUDE.md 생성
    • developing-cast: CLAUDE.md 읽기(선택) → 코드 구현
    • engineering-act: 패키지 및 의존성 관리
    • testing-cast: pytest 테스트 파일 생성

권장 개발 흐름

1. @architecting-act  →  설계 & CLAUDE.md 생성
        ↓
2. @engineering-act   →  (필요 시) cast 생성, 의존성 추가
        ↓
3. @developing-cast   →  노드, 에이전트, 그래프, 기타 모듈 구현
        ↓
4. @testing-cast      →  테스트 작성 및 실행

노드 구현

노드 생성

각 Cast는 서로 다른 사용 사례를 위한 두 가지 유형의 베이스 노드를 포함합니다:

  • BaseNode: 동기 작업용 (파일 I/O, 데이터베이스 쿼리)
  • AsyncBaseNode: 비동기 작업용 (API 호출, 동시 작업)

노드 시그니처

노드에 필요한 것에 따라 적절한 시그니처를 선택하세요:

# 단순 - state만 필요
def execute(self, state):
    return {"result": "value"}

# config 포함 - thread_id, tags 등이 필요
def execute(self, state, config):
    thread_id = config.get("configurable", {}).get("thread_id")
    return {"result": "value"}

# runtime 포함 - store, stream 기능이 필요
def execute(self, state, runtime):
    runtime.store.put(("memories", "1"), {"key": "value"})
    return {"result": "value"}

# 전체 - 모든 기능이 필요
def execute(self, state, config, runtime):
    # 모든 기능에 접근
    return {"result": "value"}

구현 예제

Node (동기) 및 AsyncNode (비동기)의 실제 예제는 casts/chat/modules/nodes.py를 참조하세요.

테스트 및 품질 관리

테스트(pytest)

uv run pytest -q

품질 관리(ruff)

uv run ruff check . --fix
uv run ruff format .

pre-commit

본 템플릿은 pre-commit 구성을 포함합니다.

  • ruff: 코드 품질 점검/포맷/임포트 정리
  • uv-lock: 의존성 락 파일 동기화

검사 실패 시 커밋이 차단됩니다. 모든 훅을 통과해야 커밋이 완료됩니다.

라이선스

이 모노레포 템플릿의 구조와 도구는 Proact0의 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다.

자주 하는 질문(FAQ)

  • Q. 특정 Cast만 개발하려는데 의존성 설치를 최소화할 수 있나요?
    • A. uv sync --package <패키지명>으로 필요한 Cast만 설치하세요.
  • Q. 새 그래프 키를 추가했는데 Studio UI에 보이지 않습니다.
    • A. langgraph.json의 graphs에 올바른 경로(path:callable)로 등록되어 있는지 확인하고, 서버를 재시작하세요.
  • Q. 포맷/린트 기준은 어디서 확인하나요?
    • A. pyproject.toml의 [tool.ruff] 설정을 확인하세요.

참고

본 템플릿은 Proact0에서 관리하고 있습니다.