이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

AX Wiki 안내

상태: 활성 범위: 현재 상태 최종 검토: 2026-10-03 담당: AX Code 런타임

AX Wiki는 AX Code의 네이티브 저장소 위키 컴파일러입니다. 추적된 소스, 구성, 시험, 워크플로, 기존 문서를 .ax-wiki/ 아래의 작은, 소스가 뒷받침하는 Markdown 지식 기반으로 바꿉니다. AX Code와 같은 공급자 구성과 모델 라우팅을 사용합니다. 별도의 실행 파일이나 자격 증명 저장소는 없습니다.

ax-code wiki viz은 컴파일된 페이지와 그 페이지가 인용하는 파일을 그립니다. 그 지도의 스크린샷은 Wiki 증거 시각화에 있습니다.

어디에 맞는가

Wiki 산문은 컴파일된 탐색 계층이지 구조적 증명이 아닙니다. 위키와 코드가 다르면 코드를 신뢰하고 ax-code wiki update을 실행합니다.

빠른 시작

AX Code 공급자를 연결한 다음 실행합니다.

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki는 AGENTS.md을 생성하고, AX Wiki 포인터 블록을 넣고, 한 워크플로에서 위키를 컴파일합니다. 모델 호출 없이 포인터를 추가하려면 --wiki-only-agents을 사용합니다.

명령

생성 옵션에는 --model provider/model, --dir <relative>, --quiet, --skip-agents, --force가 있습니다. 보호 구역 밖에서 수동으로 편집한 생성 내용을 바꾸려면 --force이 의도적으로 필요합니다.

저장소 디렉터리

v7.22.2부터 기본 출력 디렉터리는 .ax-wiki/입니다. 숨은 접두사는 AX Code가 유지하는 저장소 지식을 식별합니다. 파일을 Git이 무시하게 만들지는 않습니다. 이 지식을 커밋할지, /.ax-wiki/를 저장소의 .gitignore에 추가할지 고릅니다.

다른 상대 디렉터리를 고르려면 wiki.dir를 ax-code.json 또는 --dir docs/knowledge에 사용합니다. CLI 플래그가 우선합니다. 모든 생성, 상태, 에이전트 포인터, 백그라운드 유지보수, 시각화가 그 선택을 사용합니다. 컴파일러는 더 오래된 ax-wiki/ 디렉터리를 자동으로 감지하거나, 옮기거나, 합치지 않습니다. 패키지와 생성기 이름, ax-wiki.config.json과 ax-wiki.instructions.md는 바뀌지 않습니다.

생성된 계약

AX Wiki는 Markdown 페이지와 .ax-wiki/.manifest.json을 씁니다. 각 페이지의 프론트매터에는 다음이 있습니다.

• generated_by: ax-wiki
• 간결한 summary
• 증거가 뒷받침하는 생성에서 반환된 정확한 symbols
• 페이지를 컴파일하는 데 쓴, 저장소 상대의 sources

매니페스트는 결정적 계획 해시, 저장소 소스 해시, 페이지 해시, 생성 모델, git 리비전, 생성 시간을 저장합니다. 페이지는 원자적으로 쓰입니다. 매니페스트는 메모리 안의 완전한 후보가 검증을 통과한 뒤에만, 마지막으로 쓰입니다.

소스 발견은 Git의 추적되고 무시되지 않은 파일 목록을 선호하고, 생성/빌드/벤더 디렉터리와 위키 자신을 제외하며, 바이너리나 너무 큰 파일을 건너뛰고, 저장소 밖의 경로나 심볼릭 링크를 거부합니다.

하위 시스템 탐색

기본 계획은 빠른 시작, 아키텍처, 개발 페이지를 유지합니다. 한 페이지의 소스 수나 증거 바이트 예산을 넘는 모듈은 modules/core/src/session.md 같은 집중 페이지를 받을 수도 있습니다. 이 페이지는 모듈의 src, lib 또는 app 디렉터리 아래 직접 하위 디렉터리를 다루며, 하위 시스템마다 코드 파일이 최소 세 개이고 모듈에 자격이 있는 하위 시스템이 최소 두 개입니다.

하위 시스템 페이지에는 구현 하위 트리와, 모듈의 test 또는 tests 디렉터리 아래의 일치하는 파일이 포함됩니다. 생성 지시는 진입점, 런타임 흐름, 경계, 구체적인 변경 위치, 관련 시험을 요청합니다. 모듈 페이지는 순위가 가장 높은 소스 바로 뒤에 시험 파일을 최대 두 개 두어, 시험이 제한된 증거 선택에 참여할 수 있게 합니다.

기본 총예산은 개요 페이지 세 개를 포함해 12페이지로 남습니다. 모듈 개요와 하위 시스템 페이지는 남은 자리를 소스 수로 경쟁합니다. 하위 시스템은 부모 개요 뒤에만 포함됩니다. 따라서 더 큰 하위 시스템이 더 작은 패키지 페이지를 밀어낼 수 있습니다. ax-code wiki plan로 결과를 미리 봅니다. 자동 계획에서는 maxPages를 올립니다(최대 40). 특정 하위 시스템의 커버가 보장되어야 하면 명시적인 pages을 구성합니다. 명시적 계획은 권위로 남으며 자동 하위 시스템 페이지를 받지 않습니다.

이것은 탐색과 증거 초점을 개선합니다. 생성된 산문을 검증하거나 에이전트가 위키를 읽는다고 보장하지는 않습니다. 구현 세부 정보에 의존하기 전에 인용을 따라 현재 소스로 돌아가십시오.

에이전트가 위키를 쓰는 방법

에이전트는 가장 싼 것에서 가장 구체적인 것까지 세 가지 방법으로 위키에 도달합니다.

1. 프롬프트 색인. 건강한 위키가 있으면 세션 프롬프트에 짧은 <repo_wiki> 블록이 실립니다. 위키 위치, 신선도 레이블, 페이지당 한 줄(경로와 다듬은 요약, 기본 12페이지에 약 750토큰)입니다. 요약은 어디를 읽을지만 알려 줍니다. 증명이 아닙니다.
2. repo_wiki 도구. 연산이 세 개인 읽기 전용 도구입니다. index(페이지별 신선도가 있는 페이지 카드), read(페이지 하나와 인용한 소스, 어떤 인용 소스가 바뀌었는지, 그 소스에서 찾지 못한 프론트매터 기호), related(기호, 본문 언급, 소스 경로에 대한 페이지)입니다. 전체 도구 프로파일과 코딩 도구 프로파일에서 사용할 수 있으며 read 권한을 사용합니다.
3. 일반 파일 도구. read, glob, grep를 .ax-wiki/에 써도 계속 동작합니다.

프롬프트 신선도는 페이지마다 판단합니다. 페이지가 인용하는 모든 소스가 여전히 매니페스트 해시와 맞으면 그 페이지는 신선합니다. 어떤 페이지도 인용하지 않는 추가되거나 편집된 파일은 프롬프트 레이블을 fresh로 두고, 위키가 아직 그것을 다루지 않는다는 메모를 더합니다. 인용된 소스가 바뀌면 레이블을 stale로 표시하고, 프롬프트는 에이전트에게 위키를 탐색으로만 취급하라고 요청합니다. ax-code wiki status과 wiki lint은 더 엄격한 저장소 전체 판정을 유지합니다. 자격이 있는 파일이 추가, 제거, 편집되면 낡습니다.

위키는 소스를 대체하지 않습니다. 모든 read 결과는 대조해 확인할 파일을 나열하고, 페이지와 코드가 다르면 코드가 이깁니다.

증분 갱신과 수동 내용

wiki update는 현재 소스 해시를 매니페스트와 비교하고, 각 페이지의 선택자를 통해 변경을 대응시킵니다. 계획이 바뀌면 계획된 모든 페이지를 다시 생성합니다. 그렇지 않으면 관련 없는 페이지는 그대로입니다.

생성된 산문은 컴파일러가 소유합니다. 지속되는 유지관리자 텍스트는 보호 블록 안에 둡니다.

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

보호된 본문은 재생성 뒤에도 남습니다. --force을 주지 않으면 AX Wiki는 다른 수동 편집을 덮어쓰기를 거부합니다. 낡은 생성 페이지는 관리되는 내용이 바뀌지 않았고 보호 구역이 없을 때만 제거됩니다.

구성

프로젝트 ax-code.json에서 통합을 구성합니다.

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include, exclude, maxSourceBytes, maxPageSourceBytes가 증거 발견과 예산을 제어합니다. instructions은 프로젝트별 컴파일러 안내를 더합니다. 완전히 선별한 계획에는 pages 항목을 구성하고, 그 안에 path, title, purpose, selectors을 둡니다. 명시적 계획에는 quickstart.md가 포함되어야 합니다.

generationConcurrency은 1 또는 2를 받습니다. 네이티브 클라우드 생성은 기본적으로 동시에 페이지 호출을 두 개 합니다. 로컬 엔진과 CLI 공급자는 기본이 하나입니다. 공급자가 겹치는 요청을 대기열에 넣거나 제한하면 1으로 설정합니다. 일정은 기존 페이지 내용을 무효화하지 않습니다. 이 설정을 주지 않으면 재사용 패키지는 직렬로 남습니다.

각 모델 페이지는 180초 기한을 공유하는 분류된 시도를 최대 두 번 받습니다. 상대 Wiki 링크는 페이지가 받아들여지기 전에 페이지 계획과 대조됩니다. 깨진 링크 응답은 남은 시도로 그 페이지를 고칠 수 있습니다. 최종 검증과 수동 내용 가드는 게시 전에 여전히 실행됩니다.

중단된 빌드는 검증된 결과를 .ax-wiki/.page-cache/(또는 구성된 Wiki 디렉터리)에 유지합니다. 이후 빌드는 현재 소스 증거, 계획, 생성기, 모델, 이전 내용을 확인한 뒤에만 일치하는 결과를 다시 사용합니다. 처음 생성은 완전한 후보가 검증을 통과할 때까지 게시되지 않습니다. 성공한 게시는 소비된 스테이징 항목을 제거합니다. 이후의 명시적 wiki generate은 여전히 모든 페이지를 다시 생성합니다. 캐시 항목은 제한되고 권한으로 게이트됩니다. 손상되었거나 접근할 수 없는 항목은 무시됩니다.

.build-report.json는 모델이 생성한 페이지와 캐시된 페이지를, 실제로 게시된 written 페이지와 구분합니다. 선택적 pages 배열은 공급자가 제공할 때 각 페이지의 시도, 시간, 프롬프트/소스 바이트 크기, 정확한 토큰 사용량을 기록합니다. 실패하거나 취소된 빌드는 게시된 페이지를 보고하지 않습니다.

컴파일러 안내는 ax-wiki.instructions.md에, 핵심 엔진 구성은 ax-wiki.config.json에 둘 수도 있습니다. 둘 다 있으면 명시적인 AX Code 런타임 설정이 핵심 구성을 재정의합니다.

기본 대화형 유지보수

AX Code TUI에서 프로젝트를 열면 기본적으로 백그라운드 Wiki 유지보수가 켜집니다. 프로젝트가 30초 동안 유휴이면 없는 아티팩트가 생성되고 낡은 아티팩트는 증분 갱신됩니다. 바쁘거나 재시도 중인 세션, 대기 작업, 비어 있지 않은 초안이 우선하며 백그라운드 생성을 취소합니다. 현재 에이전트의 읽기/쓰기 권한이 적용됩니다. 읽기 전용 에이전트는 생성하지 않습니다. 이 백그라운드 워크플로는 에이전트 지시 파일을 다시 쓰지 않습니다.

백그라운드 유지보수를 끄려면 "wiki": { "auto": false }를, 컴파일과 프롬프트 주입을 끄려면 enabled: false를 사용합니다. auto의 기본값은 참이며 구성을 쓰지 않습니다. 구성된 Wiki 모델이나 AX Code 기본 모델을 사용하고, 작업 기한은 10분이며 백오프와 함께 자동 시도를 최대 세 번 합니다. 명시적인 그래프 요청이나 소스/구성 변경은 다른 시도를 허용합니다. 헤드리스 실행과 CI는 대화형 스케줄러를 켜지 않습니다. Git이 아닌 디렉터리는 명시적 요청이 필요합니다. Git 프로젝트에서 Wiki 생성과 소비는 가장 가까운 작업 트리 루트를 사용하므로, 패키지 안에서 AX Code를 열어도 별도의 패키지 Wiki가 만들어지지 않습니다.

세션 사이드바와 /wiki-viz은 로컬 진행 페이지를 바로 열고 유지보수를 요청합니다. 스냅샷이 준비되면 그 페이지는 기록된 Wiki 페이지/소스 관계를 보여 줍니다. Wiki 시각화를 보십시오.

에이전트 라우팅

건강한 위키가 있고 wiki.enabled이 false가 아니면, 세션 프롬프트는 간결한 <repo_wiki> 프로토콜을 받습니다. 에이전트에게 빠른 시작에서 시작하고, 관련된 페이지만 불러오고, 중요한 주장은 인용된 파일로 검증하고, 구조적 질문에는 그래프/LSP 도구를 쓰라고 말합니다.

healthy은 위키 디렉터리, 색인, 매니페스트가 있는지를 설명합니다. 별도의 freshness 필드는 fresh, stale 또는 unknown입니다. 상태와 세션 라우팅은 유효한 포함/제외와 크기 설정으로 현재 소스 해시를 비교하므로, 커밋되지 않은 편집, 추가, 삭제가 감지됩니다. 검사는 캐시된 신선 판정을 다시 쓰지 않습니다. 제한된 읽기 동시성으로 자격이 있는 소스를 훑습니다. 없거나 꺼진 위키는 소스 훑기를 피합니다. 신선도는 시점의 소스 검사이지, 생성된 모든 주장이나 페이지의 검증이 아닙니다. 아티팩트 검증에는 lint를 사용합니다.

낡거나 검증되지 않은 위키는 탐색용으로 계속 사용할 수 있으며, 구현 주장에 의존하기 전에 현재 원본 소스를 검증하라는 명시적 지시가 있습니다. 검증 오류는 unknown을 냅니다. 위키 디렉터리가 없으면 wiki status은 0으로 끝납니다(없는 위키가 보고서입니다). 위키가 있으면, 위키가 건강하지 않거나 신선도가 fresh이 아닐 때 실패로 끝납니다.

Wiki 증거는 제한됩니다. 고른 각 소스는 페이지 예산 안에서 처음 32,000바이트까지만 기여하고, 생성기를 위해 잘림이 표시됩니다. GraphContext는 고른 조각을 더할 수 있지만 각 조각은 80줄로 제한됩니다. 이 탐색 보조가 바뀐 모든 함수나 필요한 가드를 보존한다고 보장하지는 않습니다. 범위가 있는 검토에는 필요한 원본 코드를 따로 제공하십시오.

관리되는 <!-- AX-WIKI:START --> 블록은 AGENTS.md에 있으며, 위키 내용을 저장소 지시로 복사하지 않고 같은 라우팅 정책을 담습니다.

CI

공급자 인증이 있는 작업에서 ax-code wiki update 다음에 ax-code wiki lint를 실행한 뒤 문서 PR을 엽니다. examples/ax-wiki-update.yml를 보십시오. 생성된 위키 변경은 다른 문서처럼 취급합니다. 소스 인용을 검토하고 모델 출력을 자동 병합하지 마십시오.

문제 해결