querytree

English

에이전트가 답을 내리고 끝내지 않게 한다. 사람은 화면에서 선택·보류·재검증하고, Codex와 Claude Code는 같은 결정 상태를 읽는다.

Querytree는 AI 에이전틱 개발에서 나오는 질문, 선택지, 근거, 반론, 사용자 결정을 한 화면에 모으는 로컬 결정 콘솔과 MCP 서버다. 설계 논의가 대화 기록 속으로 사라지거나, 에이전트의 그럴듯한 답이 확인 없이 코드로 굳어지는 문제를 막는다.

왜 Querytree인가

에이전트는 빠르게 제안할 수 있지만, 제안이 사실인지·전제가 충분한지·다른 선택지를 버려도 되는지는 별도의 판단이다. Querytree는 그 차이를 상태 모델로 강제한다.

flowchart LR
    U["사용자"] -->|"선택·확정·재검증"| W["로컬 결정 콘솔"]
    C["Codex"] -->|"근거·반론·초안"| M["Querytree MCP"]
    A["Claude Code"] -->|"근거·반론·초안"| M
    W --> S["결정 상태 + revision"]
    M --> S
    S -->|"확정된 결정만"| D["workflow / ADR / 구현"]

동작 원리

사용자가 “이 HTML 보드의 시장 데이터 방식을 정해야 해”라고 말하면 에이전트는 결정을 초안으로 만들고 A/B/C 선택지와 근거·반론을 채운다. 사용자는 Querytree 화면에서 선택지를 고르고, 필요한 만큼 재질의와 재검증을 반복한 뒤에만 확정한다.

초안 -> 조사 중 -> 선택지 준비 -> 임시 선택 -> 사용자 확정 -> 구현 반영
                                           ^                 |
                                           +---- 재검증 ------+

에이전트 MCP 도구에는 확정, 선택, 재개방이 없다. 에이전트는 결정 초안, 근거, 반론만 추가할 수 있다. 이 제약은 UI·MCP 도구 계약의 경계다. 프로젝트 파일을 직접 수정할 수 있는 에이전트까지 막는 보안 경계는 아니므로, 중요한 프로젝트에서는 호스트 권한 정책과 Git review를 함께 사용해야 한다.

현재 POC

기능	상태
로컬 웹 콘솔	구현됨
선택지, 근거, 반론, 사용자 확정, 재검증	구현됨
revision 충돌 감지	구현됨
stdio MCP: 조회, 초안, 근거, 반론	구현됨
Codex/Claude Code 설치 도우미	설계 중
대화창 내 MCP Apps UI	호스트별 POC 예정
ADR·Issue·PR 자동 연결	예정

빠른 시작

Node.js 20 이상이 필요하다.

git clone https://github.com/sp-daewoon/querytree.git
cd querytree
npm install
npm run serve

브라우저에서 http://127.0.0.1:4317이 열린다. 결정 데이터는 대상 workspace의 .querytree/state.json에 저장된다. 다른 프로젝트를 대상으로 열려면 다음처럼 실행한다.

node src/cli.mjs serve --workspace /path/to/project --open

Codex와 Claude Code 연결

두 호스트의 공통 기반은 stdio MCP다. 현재는 소스 기반 POC 설치를 제공한다.

# Codex: Querytree 소스 경로를 절대 경로로 바꾼다.
codex mcp add querytree --env QUERYTREE_ACTOR=codex -- \
  node /absolute/path/to/querytree/src/cli.mjs mcp --workspace /path/to/project

# Claude Code: 프로젝트 범위로 같은 MCP 서버를 추가한다.
claude mcp add --scope project querytree -e QUERYTREE_ACTOR=claude-code -- \
  node /absolute/path/to/querytree/src/cli.mjs mcp --workspace /path/to/project

등록 후 에이전트에게 “Querytree에서 이 결정을 열어 근거와 반론을 정리해”라고 요청한다. 호스트마다 호출 문법은 다를 수 있으므로 @querytree는 제품 의도를 나타내는 별칭으로 쓰고, 실제 동작은 MCP 도구와 querytree skill이 담당한다.

MCP 도구

도구	권한	목적
querytree_list_decisions	읽기	현재 결정 카드 목록 조회
querytree_get_decision	읽기	선택지, 근거, 반론, revision 조회
querytree_create_decision	쓰기	확정되지 않은 결정 초안 생성
querytree_add_evidence	쓰기	코드·공식 문서·테스트·가설 근거 추가
querytree_add_challenge	쓰기	반론, 위험, 미확인 전제 추가
querytree_console_link	읽기	사용자 콘솔 여는 방법 조회

저장과 충돌 처리

결정 하나에는 revision이 있다. 선택이나 근거 추가가 저장될 때 revision이 증가하며, 오래된 화면이나 다른 에이전트의 변경은 409 Conflict로 거절된다. 자동 병합하지 않고 최신 상태를 다시 읽게 하는 편이 의사결정 도구에는 더 정직하다.

결정 데이터의 원본은 UI가 아니라 서버가 관리하는 JSON 상태다. UI의 선택·패널·정렬 같은 표시 상태는 언제든 사라져도 되지만, 확정된 결정과 근거는 서버 상태에 남는다.

구조

.
├─ src/
│  ├─ core/        결정 상태 모델, revision, 전이 규칙
│  ├─ mcp/         Codex·Claude Code 공통 stdio MCP 서버
│  ├─ server/      로컬 HTTP API와 콘솔 제공
│  └─ web/         사용자 선택·확정·재검증 화면
├─ skills/         에이전트가 따라야 할 결정 워크플로
├─ commands/       Claude Code 명령 진입점
├─ AGENTS.md       Codex·Claude Code 공통 헌법과 작업 흐름
├─ CLAUDE.md       Claude Code용 공통 규칙 진입점
├─ .codex-plugin/  Codex 플러그인 메타데이터
└─ .claude-plugin/ Claude Code 플러그인 메타데이터

개발

npm run check
npm run serve
npm run mcp

npm run check는 Node 문법 검사와 상태 전이 테스트를 실행한다.

로드맵

1. 로컬 콘솔과 stdio MCP POC 안정화
2. Codex·Claude Code 설치 도우미와 sample project
3. MCP Apps UI 지원 호스트의 내장 UI POC
4. 확정된 결정의 ADR, GitHub Issue, PR 연결
5. 팀 공유용 인증·원격 저장소·감사 로그

기여

Querytree는 특정 모델의 정답을 강제하지 않는다. 더 나은 반론 기록, 결정 상태, 호스트 통합, 접근성 개선 제안을 환영한다. Pull request 전에는 npm run check를 실행한다.

라이선스

MIT © sp-daewoon