코드 트레이스 트리은(는) 무엇을 하나요?
코드 워크플로우를 라인, 파일, 디렉토리 트레이스 포인트의 중첩된 트리로 구축하고 표시합니다. 제공된 Python 스크립트를 사용하여 코드 트레이스 트리 IDE 플러그인이 사용하는 하이브리드 저장소를 조작한 후, 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을 참조하십시오.
트레이스 트리 작업
모든 스킬 스크립트 호출. 이 에이전트의 절대 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을 확인합니다. 저장소가 없으면 생성합니다(사례 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>가 올바르도록 프로젝트 루트를 전달하십시오.
반환 값
표준 출력은 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은 동일한 객체의 배열입니다.
반환 값
표준 출력은 JSON입니다(indent=2, UTF-8). 노드의 skipped: true는 보장(ensure)이 해당 노드를 찾았음을 의미하며, 해당 노드의 자식은 여전히 보장됩니다. created: true는 추가(add)되었음을 의미하며, 해당 노드의 하위 항목은 보장 없이 추가되었습니다.
{
"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을 사용하십시오. CLI를 $Args라는 매개변수를 사용하는 헬퍼로 래핑하지 마십시오.
| 팁 | 결과 |
|---|---|
| 정확한 라인 + 전체 트리밍된 텍스트 | 그대로 사용 |
해당 라인의 구별되는 서브스트링(예: .handleEmailTriggerRequest() | --line 필수; 전체 트리밍된 라인 저장 |
| 2+ 라인에서 동일한 트리밍된 텍스트 | 의도된 복사본에 --line 전달; 스크립트가 발생 설정 |
| 여러 줄 호출 | 가장 구별되는 물리적 라인(종종 .methodName( 연속) 선호 |
add vs ensure: add는 항상 새 UUID를 생성합니다(IDE 플러그인과 동일). 다른 레이블이나 부모로 동일한 라인에 두 번째 노드를 추가하려면 사용하십시오. ensure는 get-or-create입니다: 동일한 ID → "skipped": true (종료 코드 0). LINE의 경우 ID는 파일 + 트리밍된 lineContent + --line으로 선택된 복사본(스크립트가 발생을 저장하며 전달하지 마십시오)입니다. FILE/DIRECTORY의 ID는 경로 + 유형입니다. --trace-name, 설명 및 부모는 ID가 아닙니다.
트리 생성: create_tree.py를 선호하십시오. 필요하지 않으면 search하지 마십시오 — 스크립트는 기존 노드를 보장하고 새 하위 트리를 추가합니다. 선택/이동/삭제 또는 검사를 위해 ID가 필요할 때 search를 사용하십시오. 단일 노드의 경우 ensure(get-or-create; 검색 불필요) 또는 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 노드.
반환 값
표준 출력은 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" 없음)