출력 모드
codeknit은 두 가지 결정을 분리합니다: 출력이 어디로 가는가(출력 모드)와 어떻게 인코딩되는가(출력 형식). 이 페이지는 각 옵션이 존재하는 이유, 비용, 그리고 적합한 경우를 설명합니다. .skt 문법에 대해서는 출력 형식 참조를, 명령어에 대해서는 parse 명령 가이드를 참조하세요.
두 가지 독립적인 선택
섹션 제목: “두 가지 독립적인 선택”--output-mode 플래그는 directory-flat, directory-tree, inline 중 하나를 선택합니다. --format 플래그는 skt(기본값) 또는 json을 선택합니다. 모든 모드는 두 형식과 조합될 수 있습니다.
두 가지 선택이 분리된 이유는 서로 다른 질문에 답하기 때문입니다. 모드는 출력이 디스크에 어떻게 분할되고 위치하는지를 결정하며, 이는 사람이나 LLM이 읽을 때 중요합니다. 형식은 누가 소비하는지를 결정합니다: LLM 또는 사람 독자, 혹은 스크립트입니다.
directory-flat
섹션 제목: “directory-flat”directory-flat는 기본값입니다. map_001.skt, map_002.skt와 같은 번호가 매겨진 청크 파일을 ./skeleton/ 디렉토리에 작성합니다(다른 출력 디렉토리를 지정하지 않은 경우).
존재 이유. 대규모 코드베이스는 하나의 컨텍스트 창에 맞지 않을 정도로 많은 구조를 생성합니다. 청킹을 통해 독자는 필요한 파일만 열 수 있어 모든 것을 로드하지 않아도 됩니다.
분할 방식. codeknit은 각 소스 파일의 블록을 intact하게 유지하며, 청크가 대략 --max-lines(기본값 500)에 도달하면 블록 사이에서 새 청크를 시작합니다. 제한은 목표일 뿐 엄격한 기준은 아닙니다: 매우 큰 블록을 가진 하나의 소스 파일은 500줄보다 긴 청크를 생성할 수 있습니다. 블록을 intact하게 유지한다는 것은 한 심볼이 같은 파일의 형제 심볼과 분리되지 않음을 의미합니다.
트레이드오프. 청크는 소스 경로로 구성되지 않습니다. 한 파일의 구조를 찾으려면 청크에서 해당 파일의 ## source-path 헤더를 검색해야 합니다. 특정 파일을 자주 조회하는 경우 directory-tree가 더 적합합니다.
미니피케이션. --minify를 사용하면 사전이 청크 옆에 있는 dict.skt에 작성됩니다. 미니피케이션을 참조하세요.
directory-tree
섹션 제목: “directory-tree”directory-tree는 소스 트리를 출력 디렉토리 아래 미러링합니다. 각 소스 파일은 일치하는 경로에 .skt 파일을 가집니다.
네이밍. codeknit은 확장자를 대체하지 않고 전체 소스 파일명에 .skt를 추가합니다. src/foo.c는 src/foo.c.skt가 되고, src/foo.h는 src/foo.h.skt가 됩니다. 이 규칙이 없으면 둘 다 foo.skt로 매핑되어 충돌합니다. 파일의 출력이 분할되면 부분은 foo.c_part1.skt, foo.c_part2.skt 등으로 명명됩니다. 대소문자만 다른 충돌을 포함한 출력 경로 충돌은 덮어쓰지 않고 명시적으로 실패합니다.
flat 모드와 다른 분할 방식. 트리 모드에서 --max-lines는 각 소스 청크에 대한 엄격한 제한이며, 최소값은 3입니다. 각 심볼 청크는 [symbols]와 ## source-path 헤더를 반복하여 단독으로 읽을 수 있습니다. 엣지만 있는 청크는 [edges]를 포함합니다. 제한은 dict.skt 및 warnings.skt와 같은 보조 파일이 아닌 소스 청크에만 적용됩니다.
트레이드오프. 트리 출력은 소스와 함께 탐색하기 쉽지만 많은 작은 파일을 생성합니다. 대규모 프로젝트는 수천 개의 파일을 생성할 수 있으며, 광범위한 개요를 원하는 독자는 많은 파일을 열어야 합니다.
inline
섹션 제목: “inline”inline은 모든 것을 stdout에 작성합니다. 출력 디렉토리나 스테이징 영역을 생성하지 않습니다.
존재 이유. 두 가지 경우에 적합합니다: 단일 파일을 빠르게 검사하거나 출력을 다른 도구로 파이핑할 때입니다. 디스크에 아무것도 작성하지 않는 유일한 모드입니다.
트레이드오프. 아무것도 분할되지 않습니다. 전체 결과가 터미널이나 소비자의 컨텍스트에 한 번에 전달되므로, 몇 개의 파일 이상에서는 독자를 압도합니다. 대략 다섯 개 미만의 파일 또는 매우 작은 프로젝트에 적합한 것으로 간주하세요. stdout은 롤백할 수 없으므로, 실패한 소비자는 부분 출력을 볼 수 있습니다. 디렉토리 모드에는 이러한 문제가 없습니다.
출력 형식
섹션 제목: “출력 형식”| 형식 | 최적의 사용처 | 출력 |
|---|---|---|
skt |
LLM 컨텍스트 및 사람 검사 | .skt 파일 또는 stdout |
json |
스크립트 및 구조화된 통합 | 디렉토리 모드에서 codeknit.json, 또는 inline 모드에서 stdout |
skt는 간결하고 줄 지향적입니다. 각 심볼은 하나의 물리적 줄에 있으며, 서명 내 줄 바꿈은 이스케이프되어, 독자가 출력 일부를 로드해도 구조가 깨지지 않습니다. 이것이 .skt에서 청킹이 작동하는 이유입니다.
json은 텍스트가 아닌 타입화된 필드를 필요로 하는 소비자를 위해 존재합니다. 이는 files, symbols, 그리고 엣지가 포함된 경우 edges를 가진 단일 문서입니다. 하나의 문서이기 때문에 줄 수로 분할되지 않습니다. 디렉토리 모드에서 --max-lines는 JSON에 영향을 미치지 않으며, 대규모 프로젝트는 하나의 큰 codeknit.json을 생성합니다.
간결한 샘플:
{ "files": ["app.go"], "symbols": [ {"id": "app.go::User", "short_id": "S1", "name": "User", "file": "app.go", "category": "type", "kind": "struct", "signature": "type User struct", "span": [3, 3]}, {"id": "app.go::Save", "short_id": "S2", "name": "Save", "file": "app.go", "category": "callable", "kind": "function", "signature": "Save(u: S1)", "span": [5, 5]} ], "edges": [ {"from": "app.go::Save", "from_short": "S2", "to": "app.go::User", "to_short": "S1", "kind": "references"} ]}모드 선택
섹션 제목: “모드 선택”| 모드 | 최적의 사용처 | 출력 |
|---|---|---|
directory-flat |
대부분의 프로젝트(기본값) | ./skeleton/map_001.skt, map_002.skt, … |
directory-tree |
소스와 함께 탐색 | ./skeleton/<미러링된 경로>.skt |
inline |
단일 파일, 파이핑 | stdout |
경험칙:
- 확신이 서지 않을 때, 기본값인
directory-flat를 사용하세요. - 단일 파일:
inline로 충분합니다. - 몇 개의 파일 이상:
directory-flat또는directory-tree를 사용하세요. - 대규모 코드베이스:
--minify를 추가하세요. - 동일한 디렉토리에 재실행:
--clean을 추가하세요.
스테이징, 재실행 및 --clean
섹션 제목: “스테이징, 재실행 및 --clean”디렉토리 모드는 출력을 즉시 출력 디렉토리에 작성하지 않습니다. codeknit은 형제 스테이징 디렉토리에서 출력을 생성하고, 생성이 성공한 후에만 게시합니다. 실패한 실행은 이전 출력을 그대로 둡니다.
기본적으로 codeknit은 선택한 형식에 대해 생성된 출력이 이미 존재할 때 작성을 거부합니다. 이유는 심볼 ID(S1, S2, …)가 추출이 변경될 때마다 바뀔 수 있기 때문입니다. 서로 다른 실행의 청크를 혼합하면 엣지가 잘못된 심볼을 가리킬 수 있습니다. --clean은 교체를 선택합니다: 성공적인 생성 후, 오래된 .skt 파일(skt 모드) 또는 codeknit.json(JSON 모드)은 교체됩니다. 디렉토리의 관련 없는 항목은 보존됩니다. 그 중 하나가 생성된 경로와 충돌하면 실행은 덮어쓰지 않고 실패합니다.
게시는 디렉토리별 잠금을 사용하며, 이전 출력을 백업하고 교체가 실패하면 복원합니다. 프로세스가 두 디렉토리 이름 변경 사이에 중단되면 다음 실행은 백업을 복원한 후 출력을 생성합니다. 이는 프로세스 실패로부터 복구됩니다. 디렉토리 업데이트가 즉각적이지 않으므로, 중단 없는 액세스가 필요한 독자는 생성을 조정해야 합니다. 또한 저장소 실패나 전원 손실로부터 보호하지 않습니다.
출력 디렉토리로 소스 디렉토리나 그 상위 디렉토리를 선택하지 마세요. 전체 게시 보장은 분석 신뢰성 참조를 참조하세요.
미니피케이션
섹션 제목: “미니피케이션”--minify는 사전 기반 압축을 적용합니다. codeknit은 callable/method 또는 exported와 같은 반복된 토큰을 짧은 코드(d0, d1, …)로 대체합니다. 매핑은 [dict] 섹션에 저장되며, 디렉토리 모드에서는 dict.skt 파일에 저장됩니다.
절약은 반복에서 비롯됩니다. 대부분의 심볼 줄은 동일한 카테고리, 종류 및 속성을 공유하므로, 대규모 코드베이스는 이러한 문자열을 수천 번 반복합니다. 비용은 간접 참조입니다: 독자는 사전을 사용하여 코드를 확장해야 하며, 단일 청크는 더 이상 자체 포함되지 않습니다. 사전은 별도의 보조 출력이므로 --max-lines에 포함되지 않습니다.
미니화된 출력은 관계 종류를 인코딩하지만 해결 마커를 읽을 수 있게 유지하므로, unresolved 및 ambiguous 엣지는 구별됩니다. 작은 프로젝트에서는 절약이 미미하며 추가 단계가 거의 가치가 없습니다. 대규모 프로젝트에서는 토큰 절약이 상당할 수 있습니다.
관련 페이지
섹션 제목: “관련 페이지”- Parse 명령 가이드: 각 모드에 대한 명령어.
- 출력 형식 참조:
.skt및 JSON 문법. - CLI 플래그 참조: 모든 플래그와 기본값.
- 분석 신뢰성 참조: 출력 네이밍 및 게시 보장.