platty Docs
플래티를 연결하고, 회사에 관해 묻고, 답의 근거를 확인하는 방법. 이 문서는 MCP로 플래티를 쓰는 모든 사람 — 현업, 기획자, 개발자, 그리고 AI 에이전트를 만드는 팀 — 을 위해 씁니다.
초안 v1 · 어드민(SSOT 관리 시스템) 문서는 개발 완료 후 추가 · 도구 이름과 예시는 현행 MCP 기준
플래티 MCP란
플래티는 별도의 앱이 아니라 MCP(Model Context Protocol) 서버로 제공합니다. 여러분이 이미 쓰는 AI — Claude, Claude Code, Cursor, 사내 에이전트 — 에 플래티를 연결하면, 그 AI가 회사의 SSOT를 도구로 조회하며 답하기 시작합니다.
AI가 얻는 것은 세 가지입니다.
- 지식 — 코드에서 만든 비즈니스 문서, 스펙, 용어사전을 검색하고 읽습니다.
- 추적 — 코드 그래프를 따라 화면→API→DB의 연결과 변경 영향을 확인합니다.
- 기억 — 구성원이 남긴 지식(메모리)을 읽고, 새 지식을 저장합니다.
연결하기
관리자에게 MCP 엔드포인트 주소와 인증 토큰을 받으세요. 접근 권한은 팀·프로젝트 단위로 관리자가 부여합니다.
Claude Code
claude mcp add platty --transport http \ https://mcp.<your-company>.platty.app \ --header "Authorization: Bearer <발급받은 토큰>"
Cursor · Claude 앱 · 기타 MCP 클라이언트
각 클라이언트의 MCP 설정에 같은 엔드포인트와 토큰을 등록합니다. 등록 뒤 도구 목록에 platty_* 도구들이 보이면 연결된 것입니다.
사내 에이전트를 만드는 팀은 같은 엔드포인트를 그대로 씁니다. 사람용과 에이전트용이 따로 있지 않습니다 — 같은 SSOT, 같은 도구입니다.
첫 질문
연결했으면 AI에게 그냥 물어보세요. 도구 이름을 알 필요는 없습니다. AI가 알아서 SSOT를 조회합니다.
# 이렇게 물으면 "셀러 정산은 언제, 어떤 기준으로 지급돼?" # AI는 내부적으로 이런 순서로 움직입니다 platty_document_search("정산 지급 기준") → 관련 사업규칙 발견 platty_document_get(...) → 규칙 본문과 근거 확인 platty_graph_trace(...) → 정산 배치의 실제 코드 위치 추적
답에는 근거(코드 위치·문서)와 신선도(어느 커밋 기준인지)가 따라옵니다. 근거가 없으면 AI는 "확인되지 않음"이라고 답합니다.
핵심 개념 — SSOT의 계층
플래티는 코드를 분석해 아래 계층을 자동으로 만듭니다. 위로 갈수록 비즈니스 언어, 아래로 갈수록 코드에 가깝습니다.
| 계층 | 무엇인가 |
|---|---|
| 프로젝트 개요 | 시스템 전체의 능력·도메인·경계 요약 |
| 에픽 | 정산·주문·캠페인 같은 업무 영역 단위. 코드를 비즈니스 단위로 재편성한 것 |
| 7종 문서 (에픽마다) | 개요 · 사업규칙 · 데이터 사전 · 시스템 설계 · 용어사전 · 액터 · 유스케이스 맵 |
| 스펙 | API·화면·이벤트·스케줄 명세. 변경 영향분석의 단위 |
| 코드 그래프 | 레포·파일·심볼과 그 연결(호출·참조·DB 접근). 모든 상위 계층의 근거 |
모든 계층은 위아래로 이어져 있습니다. 에픽에서 출발해 사업규칙 → 스펙 → 코드 위치까지 내려갈 수 있고, 반대로 코드에서 그 코드가 속한 업무로 올라갈 수 있습니다.
핵심 개념 — 근거와 신선도
- 근거(Evidence). SSOT의 모든 서술에는 근거가 되는 소스 참조가 붙습니다. 문서마다 '증거로 확인하지 못한 것' 목록도 함께 있습니다.
- 신선도(Freshness). 모든 문서에 원본 커밋과 최신 여부가 붙습니다. 코드가 바뀌면 영향받은 부분을 다시 분석하고, 낡은 문서는 낡았다고 표시됩니다. 현재 상태는
platty_context_status로 확인합니다.
핵심 개념 — 신뢰 등급
그래프의 연결선에는 출처 등급이 붙습니다.
| 등급 | 뜻 |
|---|---|
| 사람 확정 | 사람이 직접 확인하거나 이은 연결. 최상위 신뢰 |
| 정적분석 확정 | 코드 구조에서 기계적으로 증명된 연결 |
| LLM 추론 | 정적으로 잇지 못해 추론으로 이은 연결. 별도 표시되며, 사람이 컨펌하면 승격 |
답변의 근거가 어느 등급인지 함께 표시됩니다. 임의로 확정된 연결은 없습니다.
핵심 개념 — 메모리
코드에 없는 지식 — 결정의 이유, 운영 요령, 용어의 실제 의미 — 는 메모리로 저장합니다. AI와 대화하다 "플래티에 추가해줘"라고 말하면 됩니다. 메모리는 프로젝트·에픽·문서 어디에나 붙일 수 있고, 제안(proposed) 상태로 시작해 확인을 거쳐 신뢰 등급이 올라갑니다. 답변에 쓰일 때도 등급이 함께 보입니다.
도구 레퍼런스 — 프로젝트·상태
| 도구 | 하는 일 |
|---|---|
platty_project_list | 접근 가능한 프로젝트 목록 |
platty_project_overview_get | 프로젝트 개요 — 능력·도메인·경계·메모리 요약과 계층 통계 |
platty_context_status | SSOT 신선도와 검색 인덱스 상태 |
platty_workspace_repo_list | 분석된 레포 목록 — 역할·언어·프레임워크·기준 커밋 |
platty_workspace_sync_status | 레포 동기화 상태 |
도구 레퍼런스 — 탐색·검색
| 도구 | 하는 일 |
|---|---|
platty_document_search | 비즈니스 문서 의미 검색 — 질문의 출발점 |
platty_document_list / get | 에픽·유형별 문서 목록과 본문 |
platty_document_item_list / get | 문서 안의 개별 항목(규칙 하나, 유스케이스 하나) 단위 조회 |
platty_epic_list / get | 업무 영역(에픽) 카탈로그와 상세 |
platty_sot_file_get | SSOT 원문 파일 직접 읽기 |
도구 레퍼런스 — 스펙·영향분석
| 도구 | 하는 일 |
|---|---|
platty_spec_search / list / get | API·화면·이벤트·스케줄 명세 검색과 조회 |
platty_spec_impact_resolve | 변경 영향분석 — 이 스펙을 바꾸면 어디가 영향받는지 |
platty_spec_document_resolve | 스펙 → 관련 비즈니스 문서로 이동 |
platty_document_spec_resolve | 문서 → 관련 스펙으로 이동 |
도구 레퍼런스 — 용어
| 도구 | 하는 일 |
|---|---|
platty_glossary_list | 용어사전 — 표준 용어와 동의어(alias), 코드 용어 연결 |
platty_glossary_translate | 용어 번역 — 부서마다 다르게 부르는 말을 표준 용어로 |
platty_glossary_alias_add / remove | 동의어 등록·삭제 — "우리 팀은 이걸 ○○라고 불러" |
도구 레퍼런스 — 코드
| 도구 | 하는 일 |
|---|---|
platty_graph_trace | 코드 그래프 추적 — 심볼에서 출발해 호출·참조·DB 접근 연결을 따라감 |
platty_code_search | 코드 검색 |
platty_readonly_workspace_shell | 분석 워크스페이스에서 읽기 전용 명령 실행 (원본 코드 확인용) |
platty_workspace_git_history | 변경 이력 조회 — "이 규칙 언제 바뀌었어?" |
도구 레퍼런스 — 데이터
| 도구 | 하는 일 |
|---|---|
big-query_guide | 연결된 데이터 웨어하우스 사용 안내 |
big-query_list_tables / get_table_schema | 테이블 목록과 스키마 — 의미는 코드 기준으로 접지됨 |
big-query_query | 읽기 전용 질의 실행 — 자연어 질문이 검증된 쿼리가 됨 |
도구 레퍼런스 — 메모리
| 도구 | 하는 일 |
|---|---|
platty_memory_add | 지식 저장 — 프로젝트·에픽·문서에 앵커 |
platty_memory_list / get | 저장된 메모리 목록·본문 (신뢰 등급 포함) |
platty_memory_update / delete | 수정·삭제 (변경 이력 유지) |
가이드 — 시스템에 질문하기
좋은 질문의 요령은 하나입니다. 여러분의 언어로 물으세요. 용어사전이 부서의 말을 표준 용어로 번역하므로, 코드 용어를 알 필요가 없습니다.
- "체험단 캠페인 정산이 늦어지는 조건이 뭐야?" — 업무 언어 그대로
- "이 오류코드 무슨 뜻이야?" — 코드·화면·문서 어디서 봤든
- 답이 오면 근거를 확인하세요. 근거 코드 위치와 신선도가 함께 옵니다. "확인되지 않음"이 오면 그 영역은 아직 증거가 없는 것입니다 — 추측으로 채워진 답이 아닙니다.
가이드 — 변경 영향 확인
수정 전에 물으세요. "이 컬럼(또는 이 API, 이 규칙)을 바꾸면 어디가 영향받아?"
- AI가
platty_spec_impact_resolve와platty_graph_trace로 영향 범위를 잇습니다. - 결과는 세 종류로 구분됩니다 — 확정 관계(그래프에서 증명), 후보(미확정, 사유 포함), 추가 확인 필요(동적 패턴 등).
- 후보와 미확정 구간은 AI가 원본 코드를 직접 읽어(
readonly_workspace_shell) 보강합니다.
가이드 — 용어 통일
부서마다 같은 것을 다르게 부릅니다. 마케팅의 "체험단", 개발의 "purchase campaign", 데이터의 pcamp_id가 같은 것임을 용어사전이 알고 있습니다. 새 동의어는 alias_add로 등록하거나, 대화 중 "우리 팀은 이걸 ○○라고 불러, 기억해줘"라고 말하면 됩니다.
가이드 — 데이터 질의
"지난달 캠페인별 정산 총액 보여줘"처럼 물으면, AI가 테이블 의미를 SSOT에서 확인한 뒤 읽기 전용 쿼리를 만들어 실행합니다. 어떤 테이블을 왜 골랐는지가 답에 포함되므로, 숫자의 출처를 검증할 수 있습니다.
가이드 — 지식 남기기
대화 중 남길 가치가 있는 지식이 나오면 그 자리에서 말하세요. "플래티에 추가해줘." 관련 에픽·문서에 앵커된 메모리로 저장됩니다. 저장된 지식은 제안 상태로 시작하고, 동료의 확인을 거쳐 신뢰 등급이 올라갑니다. 잘못 저장했다면 "아까 그 메모리 지워줘"로 삭제할 수 있습니다.
가이드 — 에이전트 워크플로우
사내 에이전트나 코딩 에이전트를 만들 때 권장하는 호출 순서입니다.
# 1. 방향 잡기 — 넓게 platty_project_overview_get → platty_document_search # 2. 좁히기 — 업무 맥락 platty_epic_get → platty_document_get (사업규칙·유스케이스) # 3. 정확히 — 스펙과 코드 platty_spec_get → platty_spec_impact_resolve → platty_graph_trace # 4. 원본 확인 — 필요할 때만 platty_code_search → platty_readonly_workspace_shell
원칙은 위에서 아래로입니다. 비즈니스 문서에서 출발해 스펙, 코드 순서로 내려가면 토큰을 아끼면서 맥락을 잃지 않습니다. 처음부터 코드를 뒤지는 것은 마지막 수단입니다.
정책 — 보안 원칙
- 읽기 전용. 플래티의 코드·DB 접근은 읽기 전용입니다. 운영 코드를 실행하거나 데이터를 변경하지 않습니다.
- 미저장. LLM 호출에 쓴 프롬프트, 소스 조각, 요청·응답 원문은 저장하지 않습니다. 로그에는 최소 메타데이터만 남깁니다.
- 권한. 프로젝트·팀 단위로 접근을 관리합니다. 보이지 않는 프로젝트는 조회할 수 없습니다.
- 배포. 온프레미스·프라이빗 클라우드를 지원하며, 고객사 LLM 인프라(AWS Bedrock, Azure OpenAI 등)로 구성할 수 있습니다.
관리자 가이드 — 준비 중
SSOT 관리 시스템(커버리지 시각화, 수동 연결, 신뢰 등급 관리, MCP 연결·보안 관리) 문서는 기능 출시와 함께 공개합니다.
원고 메모 · 블로그와 일부 내용(신뢰 등급, 메모리)이 겹치지만 역할이 다름 — 블로그는 "왜", Docs는 "어떻게". 코드 예시의 엔드포인트 형식은 실제 배포 규격 확정 후 교체.