AI 어시스턴트가 신입 사원을 온보딩하기 위해 위키에 필요한 것

새 영업사원이 연간 플랜을 25% 할인해 줄 수 있는지 위키에 문의합니다. 답변은 '아니요'라고 말하고, 승인한 사람의 이름을 언급하며, 해당 정보가 나온 페이지로 링크를 겁니다. 아무도 방해받지 않습니다.

저는 Evergreen의 CEO이며, 모든 페이지가 Git 내 파일인 오픈 소스 위키 Folio를 구축합니다. 이것이 가상의 영업 공간에 적용된 온보딩 설정 방식입니다: Acme이라는 회사, Jamie라는 신입 사원, Marcus라는 매니저가 있습니다.

흥미로운 부분은 답변 자체가 아닙니다. 그 아래에 위키가 갖추어야 할 것이 중요합니다.

1. 페이지는 파일이다
   문서는 ext{.md}이고, 표는 ext{.table.md}이며, 양식은 ext{*.form.md}로, 모두 Git 리포지토리 안에 있습니다. PostgreSQL이 인덱스와 접근 규칙을 유지하며, 콘텐츠는 그렇지 않습니다. 어시스턴트, IDE, 그리고 브라우저의 인간 사용자는 동일한 파일들과 작업하며, 모든 변경 사항은 작성자가 포함된 커밋(commit)으로 기록됩니다.

2. Ask 모드는 페이지에서 답변하고, 출처는 규칙이다
   Folio AI는 두 가지 모드를 가진 패널입니다. 'Ask'는 읽기 전용이며, 이는 서버에서 강제됩니다. 'Agent'도 쓰기가 가능합니다.

Ask 모드. 'Sources:' 라인은 페이지로 연결되는 링크이며, 한 번의 클릭으로 해당 페이지가 열립니다.

이 마지막 줄은 마법이 아닙니다. 규칙(rule)이 없다면 어시스턴트는 공간 이름과 페이지 이름만 언급할 수 있습니다. 출처를 포함한 링크가 있는 'Sources:' 라인은 공간의 ext{.agent} 폴더 안에 있는 페이지입니다. 이것이 우리가 제공하는 시작점이며, ext{how-to-answer.md} 파일입니다.

답변하는 방법
신입 팀원을 첫 주 동안 돕는 상황을 가정합니다. 일반 지식이 아닌 이 공간의 페이지를 바탕으로 답변해야 합니다.

• 답변하기 전에 해당 공간(space)을 검색하세요. 제목만 보고 추측하지 말고, 반드시 페이지 내용을 읽어보세요.
• 답변은 간결하게 유지하세요: 두세 문단 또는 단계별 순서가 필요한 경우 짧은 목록 형태로 작성합니다.
• 항상 Sources: 라인으로 끝내고, 사용한 페이지 링크를 다음 형식으로 제공해야 합니다: [페이지 제목](/s/<공간>/p/<id>).
• 만약 페이지에 답변이 포함되어 있지 않다면 명확하게 밝히세요. 가격, 날짜, 이름 또는 규칙을 임의로 만들어내지 마십시오. 대신 "Escalation" 페이지를 사용하여 누구에게 문의해야 할지 제안하세요. .agent는 일반 페이지들의 폴더로, 공간 관리자(space administrator)만 볼 수 있거나 편집할 수 있습니다. 이 폴더의 모든 내용은 해당 공간에서 Ask 및 Agent 모드로 실행되는 모든 실행 컨텍스트에 약 60,000 문자까지 포함됩니다. 비관리자의 경우 이러한 페이지는 존재하지 않으며, 답변은 "페이지를 찾을 수 없음(page not found)"입니다. 패널에는 입력창 위에 ".agent rules (1)"이 표시됩니다.

규칙(rule)이란 텍스트 한 줄이며, Git이 이를 기억합니다.
매니저는 페이지에 다음 한 줄을 추가합니다:

Sources 라인 바로 앞에 "Next step:"이라는 제목과 함께 구체적인 행동 하나를 추가하세요.
그런 다음 새로운 대화에서 동일한 할인 질문을 합니다.

이 규칙은 다음 대화부터 적용됩니다. 이전 대화는 Cursor SDK에 초기 턴(turn)을 유지합니다. 그리고 규칙은 페이지이기 때문에 페이지 기록(page history)을 가지며, 누가 "Next step"을 추가했는지, 언제 했는지, 그리고 다른 모든 페이지처럼 복원 버튼이 있습니다.

양식(form)이란 출입구가 있는 표입니다

주말이 끝날 무렵 신규 입사자가 다섯 가지 질문에 답변합니다. 이것은 양식(form) 페이지이며, 표와 일대일로 연결됩니다: 양식 필드(form field)는 표의 열(column)입니다.

이것은 Folio가 디스크에 작성하는 내용입니다. 데모의 '기능 요청(Feature requests)' 테이블이며 (열과 행은 잘림), 저장소 자체 코덱으로 직렬화되었습니다:

---
folio: table
...

이 테이블은 일반적인 GitHub 렌더링 마크다운(Markdown) 형식이기 때문에, 새로운 답변은 'diff' 형태로 추가됩니다. 서버는 제출 시점(Submitted at)과 제출자(Submitter)를 자동으로 추가합니다. 뷰어(viewer) 역할 이상의 권한을 가진 사람은 로그인하여 제출할 수 있으며, 익명 답변의 경우 공개 플래그(public flag)와 공유 링크가 모두 필요합니다. 이 답변 테이블은 매니저에게만 제한될 수 있습니다: 신규 입사자의 제출 내용은 여전히 기록되지만, 그는 해당 테이블을 읽을 수는 없습니다.

뷰(Views)는 매니저의 받은 편지함입니다

'뷰(View)'란 테이블의 프런트 매터(front matter)에 저장되는 필터 및/또는 규칙과 정렬 기능을 의미합니다. 영상에서 언급된 '후속 조치 필요(Needs a follow-up)'는 논리적 OR 조건입니다: 할인 상한액 답변이 10이 아니거나, 준비도 점수(readiness score)가 2 이하인 경우를 말합니다. 네 개의 행이 들어가면 하나의 행만 남습니다: 15점을 작성한 사람이요.

어시스턴트는 답변할 수 없었던 것을 보고합니다

이 부분이 제가 가장 먼저 구축할 부분입니다. 세 가지 신호(signal)가 있으며, 어느 것도 누군가에게 보고서를 작성하도록 요구하지 않습니다: 저장된 각 답변에 대한 👍 또는 👎 표시, 매 답변 세 번째마다 실시하는 설문조사(

어시스턴트는 질문당 한 번 호출하며, 서버는 다음 사항을 강제합니다: 실행별 권고 잠금(advisory lock) 하에 확인 및 삽입이 이루어져야 하며, 질문은 정규화 후 비교되고, 하나의 실행 내 중복된 내용은 삭제됩니다 (비어 있는 누락 정보만 채움). 또한, 한 실행은 최대 세 개의 보고서만 유지할 수 있습니다. 누락 필드는 Markdown으로 렌더링되며, 도구 설명에는 어시스턴트가 해당 실행에서 실제로 열었던 페이지에 대한 링크가 필요합니다:

missing: {
  type: 'string',
  description:
...

'답변이 없는 질문들'. 먼저 그 사람 자신의 말이 오고, 그 아래에 어시스턴트가 재진술한 질문이 오며, 마지막으로 누락된 정보가 옵니다. 이 프레임은 링크 수정 전에 녹화된 것입니다.

인스턴스 관리자는 모든 대화를 볼 수 있습니다. 공간(space) 관리자는 자신이 관리하는 공간에 한정하여 동일한 페이지를 봅니다. 개인 액세스 토큰(personal access token)으로는 접근할 수 없습니다. 대화를 여는 행위는 감사 로그(audit log)에 기록되며, 해당 대화에는 이름과 시간이 표시된 '누가 이 대화를 열었는지' 블록이 나타납니다.

공간 관리자가 누락된 섹션을 작성하고, Jamie가 새로운 대화에서 다시 질문하며, 답변은 재무 담당자를 언급하고 '환불 정책(Refund policy)'에 링크합니다.

이 설명은 두 번째 버전입니다. 첫 번째 버전에서는 'missing'에 무엇을 넣어야 하는지만 언급했습니다. 따라서 비디오를 위해 기록한 19개 실행에서 모델은 일반 텍스트만 작성하고 페이지 링크는 한 번만 했습니다. 그래서 위의 녹화본에는 열(column)에 링크가 없습니다. 저희는 UI가 아닌 도구 설명(tool description)을 수정했고, 그 후 라이브 확인 결과 어시스턴트가 해당 실행에서 읽었던 페이지로 각각 5개의 답변이 없는 질문 모두에 링크를 제공하는 것을 확인할 수 있었습니다.

외부 에이전트를 위한 동일한 페이지

/mcp는 개인 토큰 또는 OAuth를 통해 모든 MCP 클라이언트에게 검색 및 ChatGPT 심층 리서치용 fetch를 포함하여 23개의 도구를 제공합니다. 이 클라이언트는 사용자의 권한 범위 내에서만 작동하며 그 이상은 하지 않습니다:

claude mcp add folio --transport http https://<host>/mcp \
  --header "Authorization: Bearer folio_pat_…"

다음 두 가지는 계승되지 않습니다. 외부 에이전트는 .agent를 볼 수 없으며, 내장된 어시스턴트만이 답변하지 않은 질문을 기록합니다. 외부 에이전트를 위해 패키지에는 일반 페이지와 동일한 규칙을 가진 agent-playbook.md가 있습니다.

하지 않는 것들

Folio AI는 Cursor 구독이 필요하며, 이 기능이 작동하는 페이지들은 Cursor로 연결됩니다. 현재 다른 제공업체는 없습니다.

살펴보시겠습니까?

Folio는 오픈 소스(MIT)입니다: https://github.com/evergreen-it-dev/folio. 데모는 https://demo.foliowiki.online에서 확인할 수 있습니다 (로그인 화면에서 Sam을 선택하세요; 데이터는 매일 초기화됩니다). 또한 https://foliowiki.online에서 짧은 투어를 할 수 있습니다.

도움이 되기를 바랍니다. 그리고 AI SDLC와 귀사에서도 동일하게 구현할 수 있는 방법에 대해 이야기하게 되어 기쁩니다.