코드 트레이스 트리은(는) 무엇을 하나요?
코드 워크플로우를 라인, 파일, 디렉토리 트레이스 포인트의 중첩된 트리로 구축하고 표시합니다. Code Trace Tree IDE 플러그인에서 사용하는 하이브리드 스토리지를 조작하기 위해 제공된 Python 스크립트를 사용한 후, IDE에 새로고침을 요청하세요.
사용자가 명시적으로 요청할 때에만 트레이스를 편집하거나 동기화하세요 (예: 주제 관련 노드 생성, 특정 라인에 팁 추가, 편집 후 재바인딩). 매 턴마다 자동 동기화하지 마세요.
사용자가 명시적으로 제거를 요청하지 않는 한, 기존 트레이스 포인트(rebind가 "invalid"라고 보고한 것 포함)를 절대 delete하지 마세요.
이 스킬 사용 방법
이 SKILL.md만 읽으세요. 이 스킬의 scripts/ 또는 references/ 폴더를 나열, 검색, 탐색하지 말고, API를 배우기 위해 스크립트 소스를 열지 마세요. 문서화된 Python 명령을 절대 경로로 호출하세요.
스킬 사용 중 심각한 문제가 발생한 경우에만 scripts/ 또는 references/를 열어보세요 (스크립트 누락 또는 충돌, 스토리지 손상, 또는 이 파일에서 다루지 않는 오류).
스킬 스크립트 위치
헬퍼 스크립트는 <Agent Skill Path>/code-trace-tree/scripts/ 아래에 있습니다.
Agent Skill Path는 실행 중인 에이전트의 스킬 디렉토리입니다 (code-trace-tree/의 상위 디렉토리). 프로젝트-로컬이 있으면 그것을, 그렇지 않으면 글로벌을 사용합니다. skills에서 끝나며, code-trace-tree에서 끝나지 않습니다. 경로는 npx skills와 일치합니다. 표에는 일반적인 예가 나열되어 있으며, 다른 나열된 에이전트도 동일하게 작동합니다.
| 에이전트 (예시) | 글로벌 에이전트 스킬 경로 | 프로젝트-로컬 에이전트 스킬 경로 |
|---|---|---|
| Claude Code | ~/.claude/skills | <repo>/.claude/skills |
| Cursor | ~/.cursor/skills | <repo>/.agents/skills |
| GitHub Copilot | ~/.copilot/skills | <repo>/.agents/skills |
| Codex | ~/.codex/skills | <repo>/.agents/skills |
| Gemini CLI | ~/.gemini/skills | <repo>/.agents/skills |
Windows에서 ~는 %USERPROFILE%입니다. Agent Skill Path는 세션당 한 번만 확인하세요. python(PATH에 python3가 있으면 그것을 사용)으로 절대 경로를 사용하여 스크립트를 호출하세요. 프로세스 CWD를 IDE 프로젝트에 유지하세요 (스킬 폴더로 cd하지 마세요). 직접 호출: 트레이스 트리 작업. PowerShell에서는 Windows PowerShell도 참조하세요.
트레이스 트리 작업
모든 스킬 스크립트 호출. THIS 에이전트의 절대 Agent Skill Path를 대체하세요. 프로세스 CWD를 IDE 프로젝트에 유지하세요 (스킬 폴더로 cd하지 마세요). PowerShell에서는 Windows PowerShell을 참조하세요.
- resolve_storage.py
- create_tree.py
- trace_tree.py
- request_refresh.py
- request_refresh_profile.py
- request_refresh_settings.py
- select_trace_points.py
resolve_storage.py
프로젝트 ID와 바인딩된 글로벌 XML을 확인합니다. 스토리지가 없으면 생성합니다 (Case C). .idea/code-trace-tree.project.id 파일이 있지만 XML이 없으면 동일한 projectId로 XML을 재생성합니다. .idea id 파일을 생성하거나 덮어쓰지 않습니다. create_tree 및 trace_tree add / ensure / move / delete / rebind 변형 작업도 자동으로 스토리지를 생성합니다. trace_tree search는 자동 생성하지 않습니다.
사용법
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" [project_path]
선택적 매개변수:
[project_path]: IDE 프로젝트 루트를 찾는 데 사용되는 경로 (기본값: CWD). XML<path>가 올바르도록 프로젝트 루트를 전달하세요.
반환 값
Stdout은 JSON입니다 (indent=2, UTF-8). 오류는 stderr에 ERROR: …를 출력합니다.
{
"created": false,
"project_root": "<abs>",
"global_dir": "<OS Config Dir>/code-trace-tree",
"project_id": "<uuid or null>",
"storage_xml": "<abs xml path>"
}
created는 새 XML이 작성된 경우 true입니다. 성공 시 종료 코드 0; 프로젝트 루트를 찾을 수 없으면 1.
예제:
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py"
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" /path/to/project
create_tree.py
한 번의 호출로 중첩된 트레이스-포인트 트리를 생성합니다. 페이로드 루트만 확인합니다 (그리고 이미 존재하는 루트의 자식). 노드가 생성되면 해당 하위 노드는 추가됩니다 (자식별 확인 없음). 필요하지 않으면 search하지 마세요 — 이 스크립트는 이미 기존 노드를 확인합니다. ID가 필요한 경우(선택/이동/삭제) 또는 검사가 필요할 때 search를 사용하세요. LINE 로케이터는 trace_tree.py와 동일합니다 (file + line + content). 라인-콘텐츠 발생(occurrenceIndex / totalOccurrences)은 무시하세요 — 스크립트가 계산합니다. PowerShell에서는 --tree-file을 선호합니다.
선택적 --parent-id는 페이로드를 기존 노드 아래에 연결합니다 (해당 부모는 확인되며, 보장되지 않음).
사용법
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree '<json>'
필수 매개변수 (정확히 하나의 트리 소스):
--tree-file <path>: JSON 파일 (-= stdin).--tree보다 이것을 선호하세요.--tree <json>: JSON 문자열.- 위치 인수
<path>:--tree-file과 동일합니다.
매개변수 (공유; 모두 선택 사항):
--project <path>: 프로젝트 경로 (기본값: CWD).--profile <name>: 프로필 이름 재정의 (기본값:<activeProfileName>).--dry-run: XML을 쓰거나 새로고침하지 않습니다.--no-refresh: IDE 새로고침 신호를 건너뜁니다.--parent-id <uuid>: 기존 부모; 루트 방향으로 반복 → 직계 부모. 프로필 루트의 경우 생략.--parent <json>: 기존 부모 경로 JSON (--parent-id와 함께 사용하지 마세요).
트리 JSON (하나의 노드 객체 또는 노드 객체 배열). 모든 노드는 동일한 형태를 사용하며, children을 포함합니다 (description은 모든 노드에 있으며, 루트에만 있는 것이 아님):
{
"file": "src/A.java",
"line": 10,
"content": "void methodA() {",
"name": "methodA",
"description": "",
"type": "LINE",
"children": [
{
"file": "src/B.java",
"line": 40,
"content": "void methodB() {",
"name": "methodB",
"description": "",
"type": "LINE",
"children": [
{
"file": "src/C.java",
"line": 20,
"content": "void methodC() {",
"name": "methodC",
"description": "",
"type": "LINE"
},
{
"type": "FILE",
"file": "src/Util.java",
"name": "Util",
"description": ""
}
]
}
]
}
필드 (모든 노드, 자식 포함): file (필수); type (LINE | FILE | DIRECTORY; 생략 시 추론: line/content → LINE, 그 외 디스크 경로); LINE은 line + content 필요; name / description / children 선택 사항. occurrenceIndex / totalOccurrences를 포함하지 마세요. children은 동일한 객체의 배열입니다.
반환 값
Stdout은 JSON입니다 (indent=2, UTF-8). 노드에서 skipped: true는 ensure가 노드를 찾았음을 의미하며, 해당 노드의 자식은 여전히 확인됩니다. created: true는 추가를 의미하며, 해당 노드의 하위 항목은 ensure 없이 추가되었습니다.
{
"action": "create_tree",
"profile": "<profile-name>",
"storage_xml": "<abs>",
"parentId": "<uuid or empty>",
"created": 3,
"skipped": 1,
"ids": ["<uuid>", …],
"roots": [ { "skipped": false, "created": true, "node": <node-object>, "children": [ … ] } ],
"refreshed": true
}
성공 시 종료 코드 0.
예제:
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file tree.json
trace_tree.py
노드 검색, 추가, 확인, 이동, 삭제 및 재바인딩. 라인-콘텐츠 발생(occurrenceIndex / totalOccurrences)은 무시하세요 — 해당 필드를 절대 전달하지 마세요; 스크립트가 계산합니다.
사용법
python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" <subcommand> [flags…]
python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" [shared-flags] <subcommand> [flags…]
공유 플래그 (--project, --profile, --dry-run, --no-refresh)는 하위 명령 앞이나 뒤에 나타날 수 있습니다. CWD가 이미 IDE 프로젝트 내에 있으면 --project를 생략하세요 (스크립트는 위로 이동하여 .vscode / .idea / .git 또는 기타 일반 프로젝트 마커를 찾습니다). 기본 프로필: <activeProfileName>.
LINE 로케이터: 저장된 팁은 [file, line, full-trimmed-line]입니다. --line은 필수입니다. 스크립트는 해당 줄의 트리밍된 텍스트를 확인하고, 전체 트리밍된 줄을 저장한 다음 (--content의 하위 문자열은 확장됨), 파일을 스캔하여 occurrenceIndex / totalOccurrences를 설정합니다. 하나의 파일에서 중복된 트리밍 라인은 --line이 어떤 사본을 선택하느냐에 따라 구별됩니다. 발생 무시: occurrenceIndex / totalOccurrences를 읽거나, 전달하거나, 계산하지 마세요. PowerShell에서는 인용된 --content를 --%로 보호하거나(Windows PowerShell 참조) 하위 문자열 팁과 --line을 사용하세요. $Args라는 이름의 매개변수를 사용하는 헬퍼로 CLI를 감싸지 마세요.
| 팁 | 결과 |
|---|---|
| 정확한 라인 + 전체 트리밍된 텍스트 | 그대로 사용 |
해당 라인의 독특한 하위 문자열 (예: .handleEmailTriggerRequest() | --line 필요; 전체 트리밍된 줄 저장 |
| 2개 이상의 라인에서 동일한 트리밍 텍스트 | 의도한 사본에 대해 --line 전달; 스크립트가 발생 설정 |
| 여러 줄 호출 | 가장 독특한 물리적 라인 선호 (종종 .methodName( 연속) |
add와 ensure의 차이: add는 항상 새 UUID를 생성합니다 (IDE 플러그인과 동일). 다른 레이블이나 부모를 가진 동일한 라인의 두 번째 노드에 사용하세요. ensure는 가져오기-또는-생성입니다: 동일한 ID → "skipped": true (종료 코드 0). LINE의 경우 ID는 파일 + 트리밍된 lineContent + --line으로 선택된 사본입니다 (스크립트가 발생을 저장합니다; 전달하지 마세요). FILE/DIRECTORY의 ID는 경로 + 유형입니다. --trace-name, 설명, 부모는 ID가 아닙니다.
트리 생성: create_tree.py를 선호하세요. 필요하지 않으면 search하지 마세요 — 스크립트는 기존 노드를 확인하고 새 하위 트리를 추가합니다. 선택/이동/삭제를 위한 ID가 필요하거나 검사가 필요할 때 search를 사용하세요. 단일 노드의 경우 ensure (가져오기-또는-생성; 검색 불필요) 또는 add (항상 새 UUID)를 사용하세요.
부모 경로: 루트 방향 조상 → 직계 부모의 --parent-id를 반복하는 것을 선호하세요. add / ensure에서 루트의 경우 생략. --parent-id를 --parent와 결합하지 마세요. --parent JSON 내부의 순수 문자열은 traceName 레이블이 아닌 UUID만입니다.
--parent 형식 | 예제 |
|---|---|
| 루트 | --parent [] (move에서 루트로 필요; add / ensure는 기본적으로 루트) |
| JSON의 노드 ID | --parent '["3d41c2d1-…"]' |
[file, line, content] | --parent '[["src/A.java",10,"void methodA() {"]]' |
method A def
method B call
method C call ← --parent-id idA --parent-id idB를 사용하여 추가 (또는 B가 이미 존재하면 ensure)
디스크 편집 후 재바인딩: 에이전트는 IDE 편집기를 통해 편집하지 않으므로 라인 이동이 적용되지 않습니다. 프로젝트 소스를 수정한 모든 턴 후에, 로케이터나 선택/탐색에 의존하기 전에 rebind (영향을 받은 경로에 대해 선택적으로 --file)를 실행하세요. Rebind는 트리밍된 lineContent에서 lineNumber를 복구하고 발생을 재계산합니다. "invalid" 배열은 해당 LINE 로케이터를 찾을 수 없음을 의미합니다 — 해당 노드를 트리에 그대로 두고, 사용자가 제거를 요청하지 않는 한 delete하지 마세요.
여러 변형 호출의 경우 각각에 --no-refresh를 사용하고, 마지막에 한 번 request_refresh.py를 실행하세요.
필수 하위 명령:
<subcommand>:search|add|ensure|move|delete|rebind
매개변수 (공유; 모두 선택 사항):
--project <path>: 프로젝트 경로 (기본값: CWD).--profile <name>: 프로필 이름 재정의 (기본값:<activeProfileName>).--dry-run: XML을 쓰거나 새로고침하지 않습니다.--no-refresh: IDE 새로고침 신호를 건너뜁니다.
매개변수 (search; 모두 선택 사항):
--id <uuid>: 노드 UUID.--file <path>: 상대 파일/디렉토리 경로.--line <n>: 1부터 시작하는 줄 번호.--content <text>:lineContent에 대한 하위 문자열 일치.--trace-name <text>:traceName에 대한 하위 문자열 일치.--type <LINE|FILE|DIRECTORY>: 유형별 필터.
매개변수 (add / ensure):
- 로케이터 (필수): LINE의 경우
--file+--line+--content(해당 줄의 하위 문자열도 괜찮음); FILE/DIRECTORY의 경우--file. 또는 위치 인수FILE LINE CONTENT, 또는 경로. --parent-id <uuid>(선택 사항): 부모 노드 UUID; 루트 방향으로 반복 → 직계 부모 (선호). 루트의 경우 생략.--parent <json>(선택 사항): JSON 부모 경로 (--parent-id와 함께 사용하지 마세요).--trace-name <text>(선택 사항): 트레이스 포인트 레이블.--description <text>(선택 사항): 설명.--type <LINE|FILE|DIRECTORY>(선택 사항): 유형 재정의 (기본값: LINE).
매개변수 (move):
- 로케이터 (필수):
--id, 또는--file+--line+--content, 또는 FILE/DIRECTORY의 경우 단독--file. - 새 부모 (필수):
--parent-id(루트 방향으로 반복 → 직계 부모) 또는--parentJSON. 루트의 경우--parent []를 사용하세요.--parent-id를--parent와 결합하지 마세요.
매개변수 (delete):
- 로케이터 (필수):
--id, 또는--file+--line+--content, 또는 FILE/DIRECTORY의 경우 단독--file.
매개변수 (rebind; 모두 선택 사항):
--file <path>: 상대 경로로 제한; 반복 가능. 기본값: 프로필의 모든 LINE 노드.
반환 값
Stdout은 JSON입니다 (indent=2, UTF-8). 오류는 stderr에 ERROR: …를 출력하고 0이 아닌 값으로 종료됩니다.
node-object:
{
"id": "<uuid>",
"parentId": "<uuid or empty>",
"type": "LINE|FILE|DIRECTORY",
"file": "<relative path>",
"line": "<n or empty>",
"content": "<trimmed lineContent>",
"name": "<traceName>",
"depth": 0,
"childCount": 0
}
search:
{
"project_root": "<abs>",
"storage_xml": "<abs>",
"profile": "<profile-name>",
"matches": [ <node-object>, … ]
}
add (항상 생성됨; "skipped" 없음)
…
[번역을 위해 잘림]