Repository navigation
[DOCS#1] LangGraph 멀티 에이전트 프레임워크 룰셋·문서·CI 개편 - #3
Conversation
- README: Malkuth 개요 + 8개 룰 파일 구조 + 핵심 원칙(격리/조합성/명시적 계약) 정리 - 01-architecture: 6계층 아키텍처(Control Plane/Orchestration/Runtime/Protocol/Module/Storage) 정의 - Python 3.12 + uv + LangGraph + Docker 기반 기술 스택 명시 - src/malkuth 디렉토리 구조, graph run 제어 흐름, 배포 시 계약 검증 규칙 수록 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 02-agent-implementation: BaseAgent 계약, Manifest 스펙, Docker 격리 규칙(non-root/리소스 limit/전용 네트워크), lifecycle 상태 머신, Agent Control API 정의 - 03-protocol-integration: 프로토콜 자원의 에이전트 단위 격리 원칙, A2A connection allowlist 이중 방어, MCP 서버 3가지 배치 패턴(stdio/sidecar/external), tool 네임스페이싱 및 에러 매핑 표 - 기존 02-crawler-implementation(IssueTracker 크롤러 규칙) 제거 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 04-module-system: 모듈 독립 배포 원칙 + ref@version 참조 체계 정의 - 스킬셋: skillset.yaml 스펙, 시그니처 기반 tool schema 자동 생성, 컨테이너 내 로딩 격리 - 프롬프트셋: 변수 스키마 검증, Jinja2 + locale 오버라이드, 프롬프트 변경 버저닝 - 그래프: config 기반 노드/edge/connections 배선, 배포 시 토폴로지 검증, attach/detach 시맨틱 표 - 기존 03-data-processing(IssueTracker 파이프라인 규칙) 제거 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 05-error-handling: MalkuthError 타입 + 15개 카테고리, boundary 레이어별 변환 규칙, 에러 코드 체계(LLM/A2A/MCP/RT/GRAPH/MOD), 재시도 계층 분리(이중 재시도 방지), structlog 필드 표준, Prometheus 메트릭/알림 규칙 - 06-testing: tests/ 미러링 구조 + unit/integration/e2e 마커 분리, FakeModel 표준(실 LLM 호출 금지), testcontainers 기반 Docker lifecycle 테스트, fake runtime 그래프 라우팅 테스트, 스킬셋 schema 스냅샷·프롬프트셋 golden 테스트, ruff/mypy/coverage 게이트 - 기존 04-error-handling, 05-testing(Go/IssueTracker 기준) 제거 및 번호 이동 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 07-code-style: Go 스타일 가이드를 Python 3.12 기준으로 전환 — ruff/mypy, type hint 필수, async 규칙, pydantic 모델 설계, 안티패턴 목록. 커밋/브랜치 컨벤션과 docs en/ko 이중화 정책은 유지 - 08-workflow: 핵심 6 규약(issue-first/자율 진행/commit-per-TODO/PR 자동 생성/권한 최소화/Label·Type) 이식 — repo 참조를 EinSofINTEREST/Malkuth 로 변경, 미이식 보조 도구(gh-meta.sh, PR 템플릿, lint CI)의 fallback 표 추가, Docker 조작·실 LLM 호출 비용을 자율/예외 영역에 반영 - 기존 06-code-style, 07-workflow(IssueTracker 기준) 제거 및 번호 이동 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Agent Hierarchy 섹션 신설: goal 단위 그래프 = main agent 노드 + 각 main 아래 sub-agent 팀, 역할은 코드가 아닌 배선이 결정, 중첩 위임 깊이 상한 - Execution Modes 섹션 신설: 달성형 mission(END 도달 종료) / 상주형 service(무한 iteration + idle backoff + 연속 실패 임계) 이원화, recurring mission 판단 기준 포함 - 통신 경로를 3원화: graph state / delegation(agent__ tool) / A2A peer call - 오케스트레이터 설정에 service run 슬롯·idle 기본값 추가, 배포 검증 항목에 mode·계층 규칙 반영 - README: 개요·조합성 원칙·그래프 배선 예시에 계층 및 모드 반영 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 02: Role Agnosticism 규칙(main/sub 역할은 배선이 결정, 코드에서 가정 금지), Sub-Agent Delegation 섹션 신설 — agent__ tool 등록, 위임 timeout/병렬/취소 전파/깊이 상한/usage 집계 규칙, manifest 에 역할 선언 금지 조항 - 03: subagents 계층 선언의 부모→자식 자동 allowlist(supervision connection), Agent-as-Tool 브릿지(AgentCard 기반 schema 생성, 스트리밍 중계, 에러 투명성), 통신 경로 선택 표를 Delegation/A2A/Graph edge/Skillset 4원으로 확장 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Everything Is a Module 절 신설: 솔루션(목표 단위 기능/상주 과업) = 기존 모듈 조립로 구성, 프레임워크 코드 수정 필요 시 모듈 시스템 결함으로 간주 - 그래프 spec 에 mode(mission/service)·goal 선언 추가, service 상주형 예시(feed-monitor) 수록 — idle backoff 필수, max_failure_streak, 무한 순환 허용 - Cycle Policy 를 mode 별로 분리: mission 은 END+max_iterations 필수, service 는 idle 정책 필수 - Direct 요청용 default 템플릿 호환성 규칙 추가 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- main/sub 구분·supervision 연결·agent__ 위임 tool 개념 전면 철회 — 에이전트 간 우열 관계 없음 - 01: Agent Hierarchy 섹션을 Interaction Model 로 교체 (orchestrated run / direct request / peer call 3원 접근), 오케스트레이터는 라우터일 뿐 슈퍼 에이전트 아님을 명문화 - 02: TaskRequest.node_id optional 화(direct 태스크), Direct Requests 섹션 신설 — default 템플릿, graph state 불간섭, stateless 인터랙티브 세션 규칙 - 03: A2A Peer Symmetry 규칙 추가 (방향은 선언의 문제, 상호 선언 시 양방향 협업), tool 네임스페이스 2원 복원 - README: 개요·조합성 원칙을 동등 peer 기준으로 갱신 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 05: iteration/mode 로그 필드 추가, service run 메트릭(iterations/idle gauge) 및 GRAPH_005(연속 실패 정지) 코드 신설, ServiceRunStalled/ServiceRunHalted 알림, 정지 run 재개 절차 - 06: service 모드 필수 테스트 시나리오(fake clock 기반 backoff/drain/재개/failure streak), agentd direct 태스크 처리 테스트 추가 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 메모리 scope 체계(run/agent/shared) 및 graph state 와의 역할 분리 기준 정의 — 공유는 A2A allowlist 와 동일한 선언 기반 grant - memoryset 을 버저닝 모듈로 규격화: 인덱스(임베딩 모델 고정/청킹/하이브리드 가중), 보존(TTL/compaction), recall 기본값 선언 - 하이브리드 인덱스 설계: space 단위 vector+lexical+metadata 3계층, RRF 병합, 비동기 인덱싱 파이프라인(eventual consistency 명시) - 컨텍스트 주입 규칙: auto-recall 1회 + memory_search tool, token budget/relevance threshold/supersedes dedup/provenance 표시/untrusted 경계 - Memory Service 접근 통제(per-agent token, DB 자격증명 미주입), MEM_* 에러 코드, 메모리 메트릭, 테스트 요건 수록 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 01: Module/Storage 레이어에 memoryset·Memory Service 추가, src/malkuth/memory/ 디렉토리, 저장 백엔드(sqlite-vec/pgvector), shared memory 를 사이드채널 금지의 유일한 선언 기반 예외로 명시, memory 설정 추가 - 02: Statelessness 규칙에 AgentContext.memory 경로 명시, manifest 예시에 memory.spaces 선언 추가 - 04: memoryset 을 네 번째 모듈 타입으로 등재 — 참조 형식/레지스트리/솔루션 조립 트리/모듈 테스트 기준 갱신, 정책은 모듈·권한은 배선 원칙 - 05: MEMORY 에러 카테고리 + MEM_* 코드, memory boundary 행, memory_space 필드, 메모리 메트릭 4종 - 06: memory/ 유닛 테스트 대상(ACL/RRF/예산/supersedes, fake embedder) 추가 - README: 09 섹션 안내 및 메모리 부착 quick path 추가 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 01: Resource Scoping 섹션 신설 — 그룹은 리소스 경계일 뿐 우열 아님(peer 원칙 유지), 연결에 자동 권한 없음, local > group > global 해석 순서 - groups/<name>.yaml Group 스펙 정의 (quotas/secrets/memory/artifacts), 예약 그룹 global 은 전역 스코프 선언 전용 - 스코프별 리소스 매트릭스(Secrets/Memory/Artifact/Quota), 그룹 이동·삭제·quota 검증 규칙 - 디렉토리 구조에 groups/ 추가, 배포 검증 8항목으로 확장(그룹 존재/secrets 해석/quota) - README: 개요·격리 원칙·01/09 안내에 스코프 반영 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 02: manifest metadata.group 소속 선언(최대 1개, global 직접 선언 금지), Secrets Injection 을 3계층 스코프 해석(local > group > global, shadowing 허용)으로 재정의, 그룹 quota 초과 시 기동 거부(RT_006) - 03: Group Neutrality 규칙 추가 — 그룹 소속은 A2A 연결에 자동 권한을 부여하지 않음, 리소스 스코프와 연결 배선은 직교 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 기존 agent/shared scope 를 local/group/global 로 대체 — 그룹 멤버십이 접근 경계, 그룹 간 공유는 global scope 사용 - 스코프별 선언 위치 확정: manifest(local) / 그래프(run) / group.yaml(group, 멤버 기본 rw) / groups/global.yaml(global, 기본 ro + writers 명시) - 별칭 충돌 시 local > group > global 해석, scope-부착 위치 불일치는 MOD_003 - 그룹 이동 시 토큰 재발급·이전 그룹 space 접근 상실, 영구 스코프 retention 선언 필수, ACL 테스트 케이스 갱신 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 04: 레지스트리 Scope Neutrality 규칙 — 모듈은 전역 아티팩트, 스코프는 런타임 리소스에만 적용 - 05: group 로그 필드, 에이전트 메트릭 group 라벨, RT_006(그룹 quota 초과)·CFG_002(그룹 정의/스코프 해석 실패) 코드 추가 - 06: group 스키마·스코프 해석 유닛 테스트, 비멤버 ACL·별칭 해석 메모리 테스트, quota 초과 기동 거부 통합 테스트 추가 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 기존 IssueTracker 문서(docs/architecture Go 패키지 문서, docs/ci, 구 docs/ko) 제거 - 루트 README 를 영어 + 언어 선택자 형식으로 작성 (07 문서 정책 준수) - docs/en 구조 신설: 문서 인덱스, 아키텍처 개요(계층/상호작용 모델/실행 모드/리소스 스코프), getting-started(부트스트랩 단계 명시 + 솔루션 조립 예시), 모듈 시스템 가이드, 테스트 전략 - docs/en/ci: CI 거버넌스 규약 + Required Status Checks 단일 소스 문서를 Malkuth CI 로 진화시켜 이식 (Format/Build → Lint/Type Check 매핑, 커버리지 40→70%, 부트스트랩 가드 명시) - docs/prompts/ISSUE.mdc 를 Malkuth 룰셋 참조 기준으로 갱신 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- docs/en 과 동일 구조로 7개 문서 번역: 인덱스, 아키텍처, 시작하기, 모듈 시스템, 테스트 전략, CI 규약, status checks 단일 소스 - 모든 문서 상단에 언어 선택자 적용 (07 문서 정책) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- ci-quality.yml: 기존 Format/Build/Test/Lint 를 Python 툴체인으로 진화 — Lint(ruff check+format), Type Check(mypy, Build 대응), Test(커버리지 70% 게이트), Integration Test(Docker) + 부트스트랩 가드(코드 부재 시 skip 으로 게이트 통과 유지) - ci-convention.yml: Commit Lint([카테고리]: 형식) / PR Title Lint([카테고리#이슈번호]) / Linked Issue Check(closing reference + dependabot allowlist) 이식, Branch Name Lint 정보성 체크 신규 추가 - ci-docs.yml: Docs Sync Check 신규 — docs/en↔ko 구조 미러 및 언어 선택자 검증 (07 문서 정책 강제) - ci-nightly.yml: E2E 스케줄 실행 (02:00 KST, fake provider 전제 — 머지 게이트 아님) - PULL_REQUEST_TEMPLATE.md: 규약 4 섹션 구성 (연관 이슈/구현 내용/CI 점검/영향·위험도/롤백 계획), 체크리스트는 status-checks 단일 소스와 일치 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 08-workflow: 이식 상태 표 갱신 — PR 템플릿·convention CI·quality CI 완료 표시, 규약 6 강제 수단을 ci-convention.yml 로 명시 - 06-testing: CI 스케치 yaml 을 실제 워크플로 4종 참조로 교체 (status-checks 단일 소스 연결) - 05-error-handling: runbook 경로를 docs/en/runbooks (+ko) 로 정정 - rules README: Internal Documentation 링크를 신규 docs/en 구조로 갱신 - .claude/loop.md: 상태 파일명을 malkuth 로 변경, pr-resolve-comments.sh 미이식 fallback 명시 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 상태 파일명 issuetracker → malkuth 로 변경 (loop/watch 2종) - 리뷰 기준을 Python/멀티 에이전트 기준으로 교체: None 역참조/async 취소, 격리 경계 위반, src/malkuth 레이어 의존 방향, 이벤트 루프 blocking - scripts/pr-feedback.sh 미이식 상태의 gh pr list 기반 fallback 절차 명시 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- EinSofINTEREST/Malkuth 의 Task/Bug/Feature Issue Type ID 표 수록 + 부여 명령 예시 - refactor/hotfix 라벨 생성 완료 반영, 이식 상태 표 갱신 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 코딩 에이전트가 직접 PR 피드백을 남기는 구조는 리뷰 독립성 관점에서 부적절하여 제거 - PR 리뷰는 외부 리뷰 봇(CodeRabbit 등)과 사람 리뷰어가 담당, 에이전트는 피드백 수신·반영(loop.md)만 수행 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- PR 피드백 반영의 기본 경로를 클라우드 루틴 pr-review-responder(GitHub 리뷰 webhook 발화 + 주간 안전망)로 전환 - 폴링 루프는 로컬 세션의 수동 보조 수단으로 강등 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- statusCheckRollup 실패 판정을 FAILURE 단일 값에서 완료 상태의 비정상 conclusion 전체(CANCELLED/TIMED_OUT/STALE/STARTUP_FAILURE/ACTION_REQUIRED 포함)로 확장 - 리뷰 코멘트 수집 시 comments 엔드포인트뿐 아니라 reviews 엔드포인트도 조회하도록 보정 (리뷰 요약 누락 방지), 처리 완료 판정을 본 자동화 계정의 👀/resolve 로 한정 - loop.md, ISSUE.mdc 에 GitHub 발 텍스트를 신뢰할 수 없는 데이터로 취급하는 경계 명시 (CodeRabbit 리뷰 피드백 반영)
- '!' 로 시작하는 GitHub Actions 표현식은 ${{ }} 로 감싸지 않으면 YAML 파싱이
깨짐 — if: !cancelled() 예시를 if: ${{ !cancelled() }} 로 수정 (en/ko 동기화,
CodeRabbit 리뷰 피드백 반영)
- CI 규약 1.4 신설: automerge 라벨 = 사람의 명시적 머지 승인, pr-merge-gatekeeper 루틴이 리뷰 완결/게이트/이슈 목표 3단계 검증 후 squash merge, 실패 시 라벨 제거 + 사유 코멘트 - 08-workflow 예외 영역에 automerge 예외 조항 추가 — 라벨 없는 PR 의 무인 merge 금지는 유지 - loop.md 에 merge 는 게이트키퍼 루틴 소관임을 명시 (루프는 merge 불수행) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 01: registry 설정을 ref type 별 roots(agents/graphs 포함)로 확장, 트리에 core/skill.py 및 src/malkuth/graphs(schemas/conditions) 추가로 예시 import 경로 정합화 - 02: BaseAgent.stream 을 async generator 구현 + async for 소비 계약으로 명시, spec.mcp.servers 정식 필드는 03 스펙을 따른다는 규칙 추가 - 04: breaking change 기준을 semver 로 재분류 — tool/필수 변수 breaking 변경 = major - 05: SKILL_001 코드 정의 및 boundary 변환 문구 명확화 - 06: 커버리지 강제 게이트를 src/malkuth 전체 70% 단일 스코프로 명시 (90/100% 는 리뷰 목표치) - README: 에이전트 예시를 TaskResult.completed factory 로, 그래프 예시 condition 을 importable ref 로 수정 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- loop.md: 자동 중단의 pending 분류가 절차 2 실패 predicate 를 재사용하도록 수정, 리뷰 수집 gh api 에 --paginate 명시 - docs testing: 커버리지 단일 강제 스코프(src/malkuth 70%) 로 서술 통일 - docs modules: breaking change semver 기준 동기화 - docs ci 1.4: 게이트 판정에 NEUTRAL 포함, 라벨 권한(Triage=머지 승인 권한) 주의 및 게이트키퍼의 labeled actor allowlist 검증 문서화 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reachedNext included review available in 7 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (32)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Reworks the repository’s project ruleset, bilingual documentation, and CI workflows to establish Malkuth (LangGraph-based multi-agent framework) conventions during the bootstrap phase (pre-code), including merge-gate enforcement and docs synchronization.
Changes:
- Replaced/added a comprehensive
.claude/rules/ruleset aligned to Malkuth’s architecture (agents-as-equal-peers, mission/service modes, scoped resources, memory/index rules). - Rewrote documentation: root README +
docs/enas source-of-truth with mirroreddocs/ko, plus CI governance/status-check docs. - Added/updated GitHub Actions workflows for quality gates (bootstrap-guarded), PR/commit conventions, docs sync enforcement, and nightly E2E.
Reviewed changes
Copilot reviewed 32 out of 32 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| README.md | New English root README with language selector + doc entry points and conventions summary |
| docs/prompts/ISSUE.mdc | Adds an issue-driven implementation prompt with explicit untrusted-input boundary |
| docs/ko/README.md | Korean docs index with language policy and TOC |
| docs/ko/architecture.md | Korean architecture overview mirroring docs/en |
| docs/ko/getting-started.md | Korean getting-started guide (bootstrap-aware) |
| docs/ko/modules.md | Korean module system overview and versioning rules |
| docs/ko/testing.md | Korean testing strategy and quality gates summary |
| docs/ko/ci/conventions.md | Korean CI governance, merge gates, and automerge policy |
| docs/ko/ci/status-checks.md | Korean single source of truth for required check names |
| docs/en/README.md | English docs index with language policy and TOC |
| docs/en/architecture.md | English architecture overview (layers, interaction model, scopes, memory) |
| docs/en/getting-started.md | English getting-started guide (bootstrap-aware) |
| docs/en/modules.md | English module system overview and versioning rules |
| docs/en/testing.md | English testing strategy and quality gates summary |
| docs/en/ci/conventions.md | English CI governance, merge gates, and automerge policy |
| docs/en/ci/status-checks.md | English single source of truth for required check names |
| .github/workflows/ci-quality.yml | Adds bootstrap-guarded lint/typecheck/test/integration jobs with uv + make |
| .github/workflows/ci-convention.yml | Adds PR title lint, commit lint, linked-issue check, and branch-name warning lint |
| .github/workflows/ci-docs.yml | Enforces en↔ko docs structure mirror + language selector presence |
| .github/workflows/ci-nightly.yml | Adds nightly E2E workflow (bootstrap-guarded) |
| .github/PULL_REQUEST_TEMPLATE.md | Introduces structured PR template aligned to merge gates and required checks |
| .claude/rules/README.md | Ruleset index/overview for Malkuth development standards |
| .claude/rules/01-architecture.md | Architecture principles, layers, execution modes, scoping model |
| .claude/rules/02-agent-implementation.md | Agent contracts, manifests, runtime/isolation rules |
| .claude/rules/03-protocol-integration.md | A2A/MCP integration rules and isolation/security requirements |
| .claude/rules/04-module-system.md | Module types, ref formats, registry rules, semver compatibility |
| .claude/rules/05-error-handling.md | Error taxonomy (MalkuthError), boundary mapping, retry/logging/metrics |
| .claude/rules/06-testing.md | Testing pyramid, determinism rules, CI gates, coverage enforcement policy |
| .claude/rules/07-code-style.md | Python + YAML conventions, doc language policy, git/PR conventions |
| .claude/rules/08-workflow.md | AI workflow policies (issue-first, commit-per-TODO, automerge, metadata) |
| .claude/rules/09-memory-context.md | Context memory scopes, memoryset policy spec, hybrid index/recall rules |
| .claude/loop.md | PR feedback loop process documentation for review/CI handling |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
🔒 Merge Gatekeeper 자동 검증 결과: 머지 보류
조치
Generated by Claude Code |
- step 레벨 if 로는 코드 부재 시 E2E job 이 success 로 기록되던 문제를 ci-quality 와 동일한 detect job + needs 기반 job 레벨 게이트로 수정 — skipped 로 정확히 기록 - check 이름 중복 금지 규칙에 따라 detect job 명을 "Detect Sources (nightly)" 로 구분 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
🔒 Merge Gatekeeper 자동 검증 결과: 머지 승인
조치
Generated by Claude Code |
연관 이슈
Closes #1
구현 내용
.claude/rules/01~09): IssueTracker(Go 크롤러) 기준 → Malkuth(LangGraph 멀티 에이전트) 기준 전면 개편.claude/loop.md갱신, pr-feedback 명세 삭제, 라벨 게이트 automerge 정책(1.4) 문서화CI / 머지 게이트 점검
[카테고리]: 한국어 요약)[카테고리#이슈번호] 제목)변경 영향 범위 + 위험도
.claude/,docs/, 루트 README) + CI (.github/) — 프레임워크 코드 없음롤백 계획