Porter AI 문서 저장소 가이드

Porter AI(기업용 AI 업무 플랫폼)의 공식 문서 사이트. Mintlify(mint 테마) 기반, 한국어 단일 버전.

저장소 개요

설정 파일은 docs.json 이다 (Mintlify 구버전 문서의 mint.json 에 해당).

3개 탭 구조:

탭	디렉토리	내용
Porter AI	`ko/`	제품 소개, AI·에이전트 활용, 데이터·시스템 연결, 모델 확장
앱 배포 플랫폼	`ko/dev/`	배포, CLI, 프레임워크별 예제
운영 시스템	`ko/ops/`	사용자·전역 공유 설정·OAuth 관리

snippets/ 는 Mintlify 기본 예제만 있고 실제로 사용되지 않는다.
이미지는 외부 URL(https://files.cloudtype.io/...)을 쓴다. 레거시 표기 storage.googleapis.com/files.cloudtype.io 가 ko/dev/ 일부에 남아 있으나 신규 삽입에는 쓰지 않는다.
로고는 logo/(docs.json 참조), 커스텀 사이드바 아이콘은 images/icons/ 에 둔다. images/ 의 나머지 파일은 Mintlify 템플릿 잔재다.
루트 style.css 는 커스텀 아이콘의 active 상태 색상을 보정한다. docs.json 에 등록하지 않아도 Mintlify 가 루트 style.css 를 자동 로드한다.

로컬 개발

mintlify 는 저장소 의존성이라 전역 설치 없이 실행된다.

npm install
npm start                    # = npx mintlify dev, 저장소 루트에서 실행
npx mintlify broken-links    # 내부 링크 검사

문서의 목적과 독자 (가장 중요)

제1목적: 잠재 고객이 Porter AI 가 무엇이고 왜 필요한지 명확하게 인지하게 하는 것. 기능 나열보다 “이 기능이 어떤 업무 문제를 해결하는가”를 먼저 쓴다. 독자는 3층위이며, 모든 페이지는 이 중 주 독자 1명을 상정하고 쓴다:

도입 의사결정자 — 보안, 거버넌스, 비용, ChatGPT 대비 차별점이 관심사
개발자 — MCP/REST API 연동, 앱 배포, CLI 가 관심사
AI 전문가 — 모델 선택, 에이전트 구성, RAG 품질이 관심사

핵심 차별점

문서 전반에서 일관되게 강조하는 Porter AI 의 5대 차별점:

차별점	한 줄 표현
보안	Self-Hosting / 관리형 단독 서버 — 데이터가 조직 밖으로 나가지 않음
모델 중립성	Claude·OpenAI·DeepSeek·Bedrock·OpenRouter·자체 호스팅·Flowise 를 조직이 선택
에이전틱 RAG	수백~수만 개 사내 문서를 원문 기반으로 답변에 반영하는 지식베이스
시스템 연결	MCP/REST API 로 사내 업무 시스템을 AI 가 직접 조회·호출
조직 거버넌스	전역 모델·데이터·Skills 관리, 사용량 모니터링·한도 — 개인용 AI 도구(ChatGPT)와의 핵심 차별

규칙: 새 기능 페이지를 쓸 때 이 중 어느 차별점을 뒷받침하는지 자문하고, 페이지 도입부에서 그 차별점과 연결하라.

사이드바 카테고라이징 원칙

독자 여정 순서: 그룹과 그룹 내 페이지 순서 모두 독자의 여정을 따른다. Porter AI 탭 = 도입 판단 → 업무 AI 활용 → 업무 에이전트 구성과 공유 → 내부 데이터와 지식베이스 활용 → 협업 툴 및 메신저 연동 → 모델 확장.
그룹명은 독자의 목적/과업 중심 한국어 (“내부 데이터와 지식베이스 활용” ○ / “Integrations” ✕). 개발자 대상 탭의 Getting Started, CLI 는 관례상 예외.
고아 파일 금지: 모든 .mdx 는 docs.json 에 등록한다. 미공개 문서는 브랜치로 관리하고 master 에 미등록 파일을 남기지 않는다.
새 페이지는 기존 그룹 우선 배치. 그룹 신설은 navigation 스킬의 기준 충족 시에만.
docs.json 의 네비게이션 경로는 navigation.versions[0].tabs[].groups[].pages[] 다 (tabs 가 최상위가 아님에 주의).

→ 배치 판단 절차, 고아 검사 스크립트: .claude/skills/navigation/

문서 스타일 핵심 규칙

frontmatter 3필드 필수: title(한국어), description(경어체 한 문장), icon(Font Awesome 이름 또는 /images/icons/*.svg).
- 예외: 중첩 그룹(앱 배포 플랫폼 탭의 Python·Node.js) 하위 페이지는 그룹이 icon 을 가지므로 페이지 icon 을 생략한다.
페이지 첫 요소는 <Card> 리드 요약 — 기능/개념을 한 문장으로 정의.
페이지 유형 4종과 톤:
- 마케팅형(도입 판단 그룹): 문제 제기 → Porter 의 해결 방식 → 핵심 차별점 연결 서사
- 기능 가이드형(대부분의 페이지): 정의 → 사용 방법(Steps/Frame) → 팁
- 튜토리얼형(quickstart 류): 모든 Step 에 스크린샷, 결과 확인 포함
- 레퍼런스형(모델 연동·CLI): 표 중심, 서사 최소화
컴포넌트 관례: 스크린샷은 <Frame><img className="block rounded-md" src="..." /></Frame>, 순서 절차는 <Steps>, 부가 설명은 <Accordion>, 비교표는 HTML <table>, 콜아웃은 Tip(권장)/Info(맥락)/Note(제약)/Warning(주의).
한국어 표기: 경어체(“~합니다”). 제품 개념은 원문 유지(Skills, MCP), 단 UI 라벨 인용은 화면 표기 그대로(설정 > 스킬).

→ 유형별 템플릿, 컴포넌트 상세 규칙, 용어집: .claude/skills/doc-writing/

Git / PR 관례

master · main · development 에 commit / push / PR 금지 — PR base 로도 쓰지 않는다. 회사 정본 브랜치다. git status 의 “Main branch” 표시를 신뢰하지 말 것.
작업은 이슈 브랜치 {작성자}/{티켓번호} (예: joje/cont-254) 에서 하고, PR base 는 개인 통합 브랜치 {작성자}/main 이다. 이 저장소의 이슈 키는 컨텐츠 팀 CONT 이며 cty- 는 과거 잔재다.
커밋 메시지는 한국어 단문 (예: “비교 테이블 수정”). feat: 같은 prefix 없이, subject 끝에 이슈 키(CONT-XXX)를 붙인다.
commit / push / PR 은 사용자가 명시적으로 지시할 때만 실행한다.

→ 이슈 생성, 브랜치 운용, 커밋 시퀀스의 정본은 .claude/skills/linear-issue/ 다. 여기서 중복 서술하지 않는다.

작업 유형별 스킬

작업	스킬
새 페이지 작성, 기존 페이지 수정	`.claude/skills/doc-writing/`
docs.json/사이드바 변경, 페이지 배치	`.claude/skills/navigation/`
커스텀 사이드바 아이콘 적용	`.claude/skills/custom-icons/`
품질 점검, 링크·중복·고아 검사	`.claude/skills/doc-review/`
리니어 이슈 생성, 커밋·브랜치 운용	`.claude/skills/linear-issue/`

페이지를 신설할 때는 doc-writing → navigation 순으로 둘 다 적용한다. 이 저장소의 규칙 수정은 항상 이 파일(AGENTS.md)에만 한다. CLAUDE.md 는 import 한 줄만 유지하고 내용을 추가하지 않는다.

알려진 부채 (주의)

2026-07-28 기준. 전체 107개 .mdx 중 docs.json 등록은 77개.

고아 파일 28개 (docs.json 미등록) — 새 고아를 만들지 말 것. 그중 ko/ops/* 14개는 의도적 비공개라 등록 대상이 아니다.
깨진 내부 링크 29건 / 13개 파일 — 157f771·415dc77 의 페이지 이동·삭제 이후 정리되지 않았다. 문서를 수정할 때 /ko/skills, /ko/global-*, /ko/dev/openclaw, /ko/vs-chatgpt 같은 옛 경로를 복사하지 말 것.
모델 연동 페이지 6개 분산, 스텁 페이지 22개, 중복 h2 29건.
상세 목록과 처리 방향: .claude/skills/doc-review/known-issues.md

​Porter AI 문서 저장소 가이드

​저장소 개요

​로컬 개발

​문서의 목적과 독자 (가장 중요)

​핵심 차별점

​사이드바 카테고라이징 원칙

​문서 스타일 핵심 규칙

​Git / PR 관례

​작업 유형별 스킬

​알려진 부채 (주의)