에이전트가 답을 내리고 끝내지 않게 한다. 사람은 화면에서 선택·보류·재검증하고, Codex와 Claude Code는 같은 결정 상태를 읽는다.
Querytree는 AI 에이전틱 개발에서 나오는 질문, 선택지, 근거, 반론, 사용자 결정을 한 화면에 모으는 로컬 결정 콘솔과 MCP 서버다. 설계 논의가 대화 기록 속으로 사라지거나, 에이전트의 그럴듯한 답이 확인 없이 코드로 굳어지는 문제를 막는다.
에이전트는 빠르게 제안할 수 있지만, 제안이 사실인지·전제가 충분한지·다른 선택지를 버려도 되는지는 별도의 판단이다. 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를
함께 사용해야 한다.
| 기능 | 상태 |
|---|---|
| 로컬 웹 콘솔 | 구현됨 |
| 선택지, 근거, 반론, 사용자 확정, 재검증 | 구현됨 |
| 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두 호스트의 공통 기반은 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이 담당한다.
| 도구 | 권한 | 목적 |
|---|---|---|
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 mcpnpm run check는 Node 문법 검사와 상태 전이 테스트를 실행한다.
- 로컬 콘솔과 stdio MCP POC 안정화
- Codex·Claude Code 설치 도우미와 sample project
- MCP Apps UI 지원 호스트의 내장 UI POC
- 확정된 결정의 ADR, GitHub Issue, PR 연결
- 팀 공유용 인증·원격 저장소·감사 로그
Querytree는 특정 모델의 정답을 강제하지 않는다. 더 나은 반론 기록, 결정 상태, 호스트 통합,
접근성 개선 제안을 환영한다. Pull request 전에는 npm run check를 실행한다.
MIT © sp-daewoon