scope

설치 경로와 호스트 연결

PLUGIN_ROOT는 이 진입점이 속한 설치 플러그인 루트다. skills/<id>/SKILL.md에서는 ../..이다. 공용 scripts/assets/tmpa는 플러그인 루트에 한 번만 배치한다. 스킬의 references와 보조 문서는 해당 스킬 파일 기준이다.

${PLUGIN_ROOT}와 ${PLUGIN_DATA}가 셸에 자동 설정됐다고 가정하지 않는다. 로드한 파일의 실제 위치로 루트를 확인하고, 실행할 때 실제 절대경로로 대체하거나 동일 셸 호출에서 변수를 설정한다. PLUGIN_DATA는 호스트가 제공하는 영속 데이터 경로를 우선 사용하고, 없으면 사용자 데이터 디렉터리 아래 이 플러그인 전용 경로를 사용한다. 사용자의 분석 대상 작업 디렉터리는 바꾸지 않는다. bash 예제는 bash에서 실행한다.

SKILL_ROOT는 지금 읽은 SKILL.md의 부모 디렉터리다. 이 스킬 전용 scripts/assets는 SKILL_ROOT 아래에 있다. ${SKILL_ROOT}는 설명용 표기이며 자동 설정된 환경변수가 아니다. 스크립트 실행 시 로드한 SKILL.md의 실제 위치로 절대경로를 구성한다. 프로젝트 작업 디렉터리를 스킬 폴더로 바꾸지 않는다.

실행 경로

${SKILL_ROOT}는 이 SKILL.md가 있는 디렉터리의 절대 경로로 바꿔 실행한다. 작업 디렉터리는 분석 대상 프로젝트에 유지한다. scripts/run.py는 이 플러그인의 공용 런타임을 사용하므로 스킬 폴더만 따로 복사하지 않는다.

사용자에게는 한국어로 답하라. 사용자가 다른 언어로 말을 걸었다면 그 언어를 따른다.

이 프로젝트의 분석 범위를 보여주고 바꾼다. 생성 코드·서드파티·테스트 픽스처처럼 결함을 봐도 고칠 생각이 없는 것들을 빼는 데 쓴다. 지금까지 Arachne UI 에서만 할 수 있던 일이다.

설정은 워크스페이스의 analysis.scope.json 에 남고 Arachne UI 와 같은 파일을 공유한다. 여기서 바꾸면 UI 에도 그대로 보인다.

1. 지금 상태부터 읽는다. 예외 없다.

python "${SKILL_ROOT}/scripts/run.py" scope-show --project-dir "$(pwd)"

• excluded 는 지금 빠져 있는 것, included 는 빠진 폴더 안에서 되살려 둔 예외다.
• scopeFile 은 실제로 읽고 쓰는 파일이다. 위치가 언어마다 달라서(C/C++ 은 .staticdata/config/ 아래, 나머지는 워크스페이스 루트) 뭔가 이상할 때 제일 먼저 볼 값이다.
• modules 는 C/C++ 빌드 모듈 목록이다 (다른 언어에서는 빈 목록). output 이 모듈의 식별자이자 --path 에 넣을 값이고, skipped 가 지금 빠져 있는지다. capturedSources 와 analyzedTus 가 어긋나면 아직 분석되지 않은 소스가 있다는 뜻이다.
• skippedModules 는 지금 통째로 빠져 있는 모듈들이다. 파일·디렉터리 제외와 축이 다르다 — 소스 경로가 아니라 그 모듈이 만들어 내는 빌드 산출물 경로가 들어간다. Arachne UI 도 같은 값을 쓴다.

2. 규칙을 알고 다뤄라. 여기서 틀리면 조용히 어긋난다.

가장 가까운 조상이 이긴다. 폴더를 빼면 그 아래가 전부 빠진다. 그 안에서 하나만 되살리려면 scope-include 로 예외를 만든다. 그래서 included 목록은 화이트리스트가 아니라 예외 목록이다.

glob 은 받지 않는다. **/*.test.py 같은 건 안 된다. 비교가 완전 일치라서다. 사용자가 패턴으로 말하면 먼저 매칭되는 실제 경로를 찾아 목록으로 보여주고 확정받아라. 폴더 하나로 묶을 수 있으면 그게 낫다: 항목 40개보다 디렉터리 1개가 유지 가능하다.

없는 경로는 거부된다(NO_SUCH_PATH). 오타를 그냥 받으면 아무것도 제외되지 않은 채로 "제외했습니다"가 되기 때문이다.

제외는 분석 대상 목록에만 걸린다. 헤더는 뺄 수 없다(NOT_ANALYZABLE). C/C++ 의 분석 단위는 TU, 즉 빌드에서 컴파일된 소스다. .h 는 거기 없으므로 목록에 넣어도 아무 일도 일어나지 않는다 (실측: 헤더를 넣고 분석해도 6/6 그대로였다). 헤더의 결함을 없애려면 범위가 아니라 다른 수단이 필요하다 — 그 헤더를 include 한 소스를 빼거나, 서버에서 결함을 억제하는 것이다. 사용자가 헤더를 빼달라고 하면 이 사실을 먼저 말해라. Arachne UI 에서도 헤더는 애초에 고를 수 없다.

모듈 단위 제외가 나은 경우가 있다. 빌드 도구 자신이 만든 모듈이 대표적이다 — CMake 는 구성 단계에서 컴파일러를 시험하느라 CMakeCXXCompilerId.cpp · CMakeCXXCompilerABI.cpp 를 컴파일하고, 그것들이 wrapper 를 거치면서 캡처에 그대로 들어온다 (실측: 결함의 65%가 이 파일들이었다). 이런 것은 파일을 하나씩 빼는 것보다 모듈을 통째로 빼는 쪽이 짧고 유지 가능하다. linkCommand 가 -Wl,--help 이거나 CMakeC*CompilerId 를 가리키면 그 모듈이다.

다만 사용자가 정할 일이다. build/ 아래에 configure_file 로 만든 진짜 소스를 두는 프로젝트도 있다. 무엇이 노이즈인지 우리가 단정하지 말고, modules 를 보여주고 확정받아라.

3. 적용한다

python "${SKILL_ROOT}/scripts/run.py" scope-exclude --project-dir "$(pwd)" \
  --path src/generated --path third_party

python "${SKILL_ROOT}/scripts/run.py" scope-include --project-dir "$(pwd)" \
  --path src/generated/keep_this.c

• --path 는 반복한다. 프로젝트 기준 상대경로도 되고 절대경로도 된다.
• 파일인지 디렉터리인지는 말하지 않아도 된다. 디스크를 보고 정한다.
• 하나라도 없는 경로가 섞이면 아무것도 쓰지 않고 멈춘다. 일부만 적용되면 무엇이 들어갔는지 알 수 없어서다.
• 룰셋과 달리 전체 교체가 아니다. 지금 목록에 더하고 빼는 방식이라, 빼려는 것만 말하면 된다.

모듈 단위 (C/C++ 만)

python "${SKILL_ROOT}/scripts/run.py" scope-skip-module --project-dir "$(pwd)" \
  --path /proj/build/CMakeFiles/3.28.3/CompilerIdCXX/a.exe

python "${SKILL_ROOT}/scripts/run.py" scope-unskip-module --project-dir "$(pwd)" \
  --path /proj/build/libcalc.a

• --path 는 scope-show 의 modules[].output 이다. 모듈 디렉터리 이름(libcalc.a_FFBA68…)도 받아 주지만, 파일에 적히는 값은 언제나 산출물 경로다 — 디렉터리 이름을 그대로 적으면 UI 가 적어 둔 값과 안 맞아 아무 일도 일어나지 않는다.
• 모르는 값은 거부된다(NO_SUCH_MODULE). knownModules 에 쓸 수 있는 값이 들어 있다.
• 파일·디렉터리 제외와 섞이지 않는다. 모듈을 빼도 excluded 는 그대로다.

4. 바뀌었으면 전체 재분석을 물어본다

3번이 ok: true 이고 실제로 목록이 달라졌을 때만 묻는다.

제외해도 이미 서버에 올라간 결함은 사라지지 않는다. 다음 분석부터 빠진다. 지금 정리하려면 전체 재분석이 필요하다.

물을 때 비용을 함께 말해라: revision 이 하나 더 생기고, 라이선스 슬롯을 점유하고, 전체를 다시 도는 작업이라 시간이 걸린다.

언어에 따라 권할 이유가 다르다.

• C/C++ : /statica:pre-analyze 는 바뀐 TU 만 돈다. 재분석하지 않으면 손대지 않은 파일의 옛 결함이 계속 남는다. 권할 이유가 있다.
• java · kotlin · python · csharp : pre-analyze 자체가 전량이라 다음 분석에 저절로 맞춰진다.

하겠다고 했을 때만 실행한다. 아니라고 하면 아무것도 하지 말고 끝내라.

python "${PLUGIN_ROOT}/scripts/run.py" upload --project-dir "$(pwd)"

• ok: true → message 를 전한다. 이 결과는 새 범위로 나온 것이다.
• returncode: 113 (이미 분석 중) / 114 (라이선스 한도) → 잠시 후 다시 시도하도록 안내하되, 범위 변경 자체는 이미 저장됐다고 분명히 해라.
• 그 밖의 실패도 hint 를 전하면서 범위 변경은 성공했다고 말해라.

결과 해석

• code: "NO_SUCH_PATH" → missing 에 못 찾은 경로가 있다. 오타이거나 이미 지워진 파일이다. 아무것도 바뀌지 않았다.
• code: "NOT_ANALYZABLE" → 있긴 하지만 제외해 봐야 소용없는 것이다. rejected[].reason 에 이유가 있으니 그대로 전해라. 헤더가 대부분이다. 아무것도 바뀌지 않았다.
• code: "NO_PATHS" → --path 를 하나도 주지 않았다.
• code: "NO_SUCH_MODULE" → 그런 모듈이 없다. knownModules 를 보여주고 다시 고르게 하라. 아무것도 바뀌지 않았다.
• code: "NO_MODULES" → 빌드 모듈은 C/C++ 에만 있다. 다른 언어는 scope-exclude 로 파일을 뺀다.
• code: "NEEDS_BOOTSTRAP" → 이 프로젝트가 아직 STATIC 에 연결되지 않았다 (statica-analyze-bootstrap 스킬).

범위를 바꾼 뒤 결함 수가 달라진 것은 코드가 아니라 범위가 바뀐 결과다. 결과를 보고할 때 반드시 함께 말하라. 말하지 않으면 사용자는 자기 코드가 좋아졌다고 읽는다. 특히 제외는 결함을 없앤 것이 아니라 보지 않기로 한 것이라는 점을 흐리지 마라.