에이전트가 읽는 페이지의 유실 없이 wiki.json으로 DeepWiki를 가이드하는 방법 (2026년 가이드)

먼저 이 파일이 수행하는 작업부터 살펴보겠습니다. "위키 생성 중에 리포지토리의 루트 디렉터리에서 .devin/wiki.json 파일이 발견되면, 제공된 repo_notes 및 pages를 사용하여 위키 생성을 가이드합니다. 두 필드 모두 필수이며, pages에는 최소 하나 이상의 페이지가 나열되어야 합니다."

두 필드는 서로 다른 역할을 합니다. Cognition은 이를 한 줄로 요약합니다. "Notes는 각 페이지가 작성되는 방식(how)을 가이드하고, pages는 어떤(which) 페이지가 생성될지를 결정합니다." Notes는 컨텍스트이고, Pages는 개요입니다.

그리고 이 개요는 문자 그대로 적용됩니다. 구성 참조 문서에 따르면 pages는 "명시적인 지침으로 취급됩니다. JSON에 정의한 페이지만 생성되며, 그 이상도 그 이하도 아닙니다." 문제 해결 섹션에서는 이 점을 두 번 더 강조하는데, 이는 사람들이 얼마나 자주 이 함정에 빠지는지 잘 보여줍니다. "위키는 사용자가 나열한 페이지만 생성하므로, 페이지가 없는 폴더는 나타나지 않습니다." 그리고 "기억하세요: DeepWiki는 이 배열에 포함된 페이지만 생성하므로, 누락된 페이지뿐만 아니라 모든 페이지가 존재하는지 확인해야 합니다."

따라서 가장 자연스러운 조치인 "위키가 우리 testing/ 폴더를 건너뛰었으니, 이를 언급하는 구성을 추가하자"는 자동 계획된 위키를 사용자가 작성한 정확한 페이지들로만 구성된 위키로 대체해 버립니다.

고려해야 할 엄격한 제한 사항도 있습니다. "최대 30페이지(엔터프라이즈의 경우 80페이지)", 리포지토리 및 페이지 노트를 통틀어 "최대 100개의 총 노트", 그리고 "노트당 최대 10,000자"입니다. 페이지 제목은 "고유해야 하며 비어 있어서는 안 됩니다." 페이지가 없는 파일은 자동으로 기본 계획으로 돌아가지도 않습니다. pages를 생략하거나 비워 둔 wiki.json은 "거부됩니다."

위키가 반영하는 내용을 결정하는 두 가지 세부 사항이 더 있습니다. 브랜치: "Devin은 각 리포지토리의 기본 브랜치를 인덱싱합니다." 그리고 Cognition의 팁은 "팀이 활발히 개발 중인 브랜치를 인덱싱하는 것"입니다. 노력 수준(Effort): 위키 생성은 세 가지 노력 수준 중 하나로 실행되며, "엔터프라이즈 조직은 항상 낮은 노력 수준으로 실행되며, 이 설정은 구성할 수 없습니다."

그 다음은 대상 독자입니다. DeepWiki는 사람들이 단순히 브라우징하는 용도에 그치지 않습니다. "Ask Devin은 위키의 정보를 사용하여 코드베이스에서 관련 컨텍스트를 더 잘 이해하고 찾습니다." 그리고 DeepWiki MCP 서버를 통해 외부 에이전트는 read_wiki_structure, read_wiki_contents, ask_question이라는 도구를 사용하여 이를 읽습니다. 생성되지 않은 페이지는 이들 중 누구도 읽을 수 없는 페이지가 됩니다.

누락된 페이지만 포함된 wiki.json 추가하기. 이것이 바로 위에서 언급한 함정입니다. 원하는 페이지를 얻는 대신 나열하지 않은 다른 모든 페이지를 잃게 됩니다.

repo_notes를 사용하여 커버리지 요청하기. 노트는 페이지가 작성되는 방식을 형성할 뿐, 어떤 페이지가 존재할지를 결정하지 않습니다. "scripts 폴더를 문서화해라"라는 노트는 pages에 해당 페이지가 포함되어 있지 않다면 아무런 역할도 하지 못합니다.

자동 위키를 그대로 두고 에이전트가 나머지 코드를 검색하기를 바라기. 에이전트가 코드를 검색할 수는 있지만, 특정 폴더에 대해 생성된 문서는 이름으로 파일을 찾는 것과는 완전히 다릅니다. 에이전트가 실제로 로드하는 정보는 대부분의 팀이 가정하는 것보다 훨씬 좁은 범위이며, 이 패턴은 코딩 에이전트가 실제로 읽는 것에서 다루고 있습니다.

MCP 서버를 DeepWiki로 지정하고 비공개 리포지토리도 커버된다고 가정하기. 공개 MCP 서버는 "공개 리포지토리에 대한 액세스를 제공하는 무료, 원격, 인증이 필요 없는 서비스"로 설명됩니다. 비공개 코드의 경우, Cognition은 Devin API 키를 사용하는 Devin MCP 서버를 가리킵니다.

한 클라이언트의 MCP 구성을 다른 클라이언트에 복사하기. Cognition은 이를 명확히 지적합니다. "Devin Desktop은 serverUrl을 사용하는 반면, 대부분의 다른 클라이언트는 표준 url 필드를 사용합니다. 잘못된 필드 이름을 사용하면 MCP 서버가 아무런 경고 없이 무시됩니다."

목표는 관심 있는 폴더를 포함하고, 자동 계획이 이미 생성한 유용한 모든 내용을 유지하며, 이에 의존하는 모든 에이전트에 도달하는 위키를 만드는 것입니다.

Step 1: 구성을 추가하기 전에 현재 위키 구조 기록하기

무엇이든 수정하기 전에, 현재 자동 생성된 위키에 포함된 내용을 기록해 두세요. Devin 또는 deepwiki.com에서 위키를 열고 최상위 페이지와 하위 페이지를 포함한 모든 페이지 트리를 복사합니다.

MCP 클라이언트를 사용하는 경우, 리포지토리에 대해 read_wiki_structure를 호출하도록 요청할 수 있습니다. Cognition은 이를 "GitHub 리포지토리의 문서 항목 목록 가져오기" 방법으로 설명합니다. 나중에 비교할 수 있도록 결과를 파일에 저장해 둡니다.

그런 다음 각 페이지에 유지(keep), 병합(merge), 삭제(drop) 중 하나의 레이블을 표시합니다. 사람과 에이전트가 사용하는 페이지는 유지합니다. 인접한 코드를 다루는 얇은 페이지들은 병합합니다. 아무도 설명이 필요 없는 생성된 코드나 벤더(vendor) 코드를 문서화한 페이지는 삭제합니다.

마지막으로 누락된 항목들을 나열합니다. 자동 계획이 건너뛴 폴더, 한 번도 생성되지 않은 횡단 관심사 주제(서비스 간 통신 방식, 배포 작동 방식 등), 그리고 생성된 요약이 너무 얕아서 유용하지 않은 영역들입니다.

Step 2: 원하는 모든 페이지를 포함하여 wiki.json 작성하고 repo_notes에 우선순위 지정하기

이제 누락된 부분만 채우는 것이 아니라, 전체 목록을 바탕으로 파일을 빌드합니다.

모든 "유지" 페이지와 누락된 페이지를 pages에 넣고, 각각 고유한 title과 구체적인 purpose를 부여합니다. Cognition의 가이드는 "집중할 특정 디렉터리, 파일 또는 개념을 언급"하고 "시스템이 의도를 이해할 수 있도록 충분한 세부 정보를 제공"하라는 것입니다. parent를 사용하여 "상위 수준의 개요 페이지부터 시작"하여 계층 구조를 재구축합니다.

커밋하기 전에 개수를 확인하세요. 목록이 페이지 제한을 초과하는 경우, 에이전트와 새 팀원이 가장 자주 여는 페이지를 남겨두고 관련 페이지를 병합하여 제한에 맞춥니다.

강조 및 관계 설정에는 repo_notes를 사용합니다. Cognition은 "코드베이스에서 가장 중요한 부분"을 명시하고 "시스템의 서로 다른 부분 간의 관계를 설명"하는 노트를 권장합니다. 추가할 내용이 없더라도 repo_notes 키는 유지해야 합니다. 참조 문서에 따르면 "빈 배열([])을 사용"하라고 되어 있습니다. 단일 페이지에만 적용되는 가이드의 경우 page_notes를 사용합니다.

그런 다음 문서화된 순서를 따릅니다. "파일을 커밋하고 위키를 다시 생성합니다."

Step 3: 다시 생성하고, 비교하고, 에이전트에 반영되었는지 확인하기

다시 생성된 위키를 Step 1에서 저장한 트리와 비교합니다. 모든 "유지" 페이지가 여전히 존재해야 하고, 병합된 페이지는 일관되게 읽혀야 하며, 누락되었던 폴더에 이제 페이지가 있어야 합니다. 무언가 사라졌다면 pages에서 누락된 것입니다.

브랜치를 확인하세요. 위키가 기본 브랜치를 설명하고 있지만 팀이 다른 브랜치에서 작업하는 경우, Cognition의 팁에 따라 해당 브랜치를 인덱싱에 추가합니다.

그런 다음 에이전트를 확인합니다. 팀이 사용하는 각 MCP 클라이언트에서 서버 항목이 해당 클라이언트가 기대하는 필드(Devin Desktop의 경우 serverUrl, 대부분의 다른 클라이언트의 경우 url)를 사용하고 있으며, 권장되는 엔드포인트를 가리키고 있는지 확인합니다. Cognition은 "SSE가 지원 중단될 예정이므로 /mcp 엔드포인트를 권장합니다"라고 명시하고 있습니다. 각 클라이언트에 새 페이지 중 하나에 답이 있는 질문을 던져보세요. 클라이언트가 위키를 바탕으로 답변한다면 가이드가 에이전트에 성공적으로 도달한 것입니다.

코드베이스의 형태가 바뀔 때 파일을 다시 검토하세요. 새로운 서비스가 추가되거나 모듈이 제거되면 페이지 목록을 편집해야 합니다. 위키는 파일에 적힌 내용만 생성하며, 그 이상도 그 이하도 아니기 때문입니다.

가이드된 DeepWiki는 코드가 무엇인지, 그리고 어떻게 서로 맞춰지는지 설명합니다. 이는 리포지토리에서 생성되므로 이력보다는 구조를 설명합니다. 예를 들어 모듈이 분할된 이유, 시도했다가 포기한 접근 방식, API에 대해 팀이 합의한 내용 등이 이에 해당합니다. 이러한 컨텍스트는 사람들의 머릿속과 흩어진 스레드에 존재합니다. MemoryLake는 이를 위키와 함께 보관할 수 있는 공간이므로, 에이전트가 지도와 그 뒤에 숨겨진 이유를 모두 파악할 수 있도록 돕습니다.

항목은 본인의 언어로 직접 작성합니다. 사용자의 DeepWiki, wiki.json, 리포지토리 또는 어떤 벤더의 저장소에서도 정보를 읽거나 쓰거나 삭제하지 않습니다.

Step 1: API 키 생성하기

로그인하고 대시보드에서 키를 생성합니다. 이 키를 통해 코딩 에이전트가 어떤 클라이언트에서 실행되든 사용자가 작성한 항목을 읽을 수 있습니다.

Step 2: 첫 번째 메모리 업로드하기

Step 1에서 드러났지만 생성된 페이지에는 담을 수 없는 내용부터 시작하세요. 구조 뒤에 숨겨진 결정 사항, 알려진 함정, 코드가 명확히 보여주지 않는 규칙 등이 이에 해당합니다. 항목당 하나의 결정 사항과 그 이유를 함께 기록합니다.

Step 3: AI 및 에이전트 연결하기

팀이 사용하는 코딩 에이전트를 연결합니다. 그러면 MCP를 통해 DeepWiki를 읽는 에이전트를 포함하여 모든 세션에서 위키 옆에 결정 사항들이 함께 배치됩니다.

첫 번째 차이점은 가이드 작업이 더 이상 위험하지 않다는 것입니다. 기존 트리를 기록하고 이를 바탕으로 페이지 목록을 구축하고 나면, wiki.json을 추가하는 것이 기존 내용을 대체하는 대신 커버리지를 확장하는 역할을 하게 됩니다.

두 번째는 repo notes가 제 역할을 다하게 된다는 점입니다. 커버리지가 pages에 존재할 때, 노트는 Cognition이 설계한 본래의 목적대로 자유롭게 작동할 수 있습니다. 즉, 새로운 페이지를 요청하는 대신 우선순위와 관계를 설명하여 모든 페이지의 품질을 향상시킵니다.

세 번째는 에이전트가 불완전한 지도를 바탕으로 작업하는 일이 없어진다는 점입니다. 동일한 위키가 Ask Devin과 모든 MCP 클라이언트에 제공되므로, 완전한 페이지 목록은 모든 곳에서 동시에 답변 품질을 향상시킵니다. 이는 에이전트가 그림을 재구성하기 위해 매 세션마다 코드베이스를 다시 읽어야 하는 상황에서 매우 중요합니다.

네 번째는 생성된 문서와 팀의 지식이 혼동되지 않는다는 점입니다. 코드에서 다시 생성된 위키는 "이것이 무엇인가"에 답합니다. 결정 사항은 "왜 이런 방식으로 되어 있는가"에 답합니다. 생성된 페이지에 대한 검색(Retrieval)은 유용하지만, RAG가 메모리가 아닌 이유에서 설명하듯이, 이는 팀이 결정한 사항을 기억하는 것과는 다른 작업입니다.

구성을 추가하기 전에 현재 페이지 트리를 저장하세요. 이는 wiki.json이 무엇을 삭제했는지 알 수 있는 유일한 방법입니다.

누락된 페이지뿐만 아니라 원하는 모든 페이지를 나열하세요. 위키는 정확히 pages 배열에 있는 내용만 생성합니다.

강조에는 repo_notes를, 커버리지에는 pages를 사용하세요. 노트는 페이지가 작성되는 방식을 가이드하고, 페이지는 어떤 페이지가 존재할지를 결정합니다.

제한 사항을 준수하세요. 페이지 수 제한을 초과하기보다는 관련 페이지를 병합하세요.

팀이 개발하는 브랜치를 인덱싱하세요. 다른 브랜치를 추가하지 않으면 Devin은 기본 브랜치만 인덱싱합니다.

MCP 필드를 클라이언트에 맞추세요. 잘못된 필드 이름을 사용하면 서버가 아무런 경고 없이 무시됩니다.

이유(의도)는 위키가 아닌 영구적인 곳에 보관하세요. Devin 자체의 Knowledge 항목에는 고유한 검색 규칙이 있으며, Devin이 작업 컨텍스트를 잊어버리는 문제는 문서 커버리지와는 별개의 문제입니다. 절차적 지식의 경우, 메모리를 기술(skills)로 이동하는 것도 또 다른 방법입니다.

.devin/wiki.json은 DeepWiki의 자동 계획이 대규모 리포지토리의 중요한 부분을 놓칠 때 사용하기에 적합한 도구입니다. 또한 매우 엄격하게 작동합니다. Cognition이 표현했듯이, "JSON에 정의한 페이지만 생성되며, 그 이상도 그 이하도 아닙니다."

가이드하기 전에 현재 가지고 있는 위키를 기록하세요. 해당 기록과 누락된 부분을 바탕으로 페이지 목록을 빌드하고, 강조를 위해 repo notes를 사용하고, 제한 사항을 준수하며 다시 생성하세요. 그런 다음 브랜치가 올바른지, 모든 MCP 클라이언트가 예상하는 필드로 구성되어 있는지 확인하여 위키를 읽는 에이전트가 의도한 버전을 가져갈 수 있도록 하세요.

코드 뒤에 숨겨진 이유는 별도의 레이어에 보관하세요. 생성된 위키는 구조를 설명할 뿐이며, 그 뒤에 숨겨진 결정 사항은 팀에서 나오기 때문입니다. 세션 간에 MCP 연결이 전달하는 것과 전달하지 않는 것에 대한 더 광범위한 질문은 MCP에서 누락된 메모리 레이어를 참조하세요.