Files
claude-harness/plugins/harness/scripts/techdebt.py
T
DongHyeonka ddbfc3dcc3 feat(plugin): 하네스 플러그인과 마켓을 더한다
문제: 되돌릴 수 없는 명령 차단, 비밀 값 알림, 예측·실측 장부가 소유자
기계의 ~/.claude에만 있거나 아예 없다. 다른 기계·파생 서비스·새 프로젝트는
받을 길이 없고, 훅 코드에 이력과 리뷰도 없다.

고른 방법: 이 repo를 플러그인 마켓으로 두고 공통 플러그인 harness 하나를
싣는다(설계 harness/01-harness-design.md 11절, 결정 Q13 (c)·Q15).
- H12(PreToolUse Bash): 호스팅 원격 force push·--mirror·보호 브랜치 지우기,
  작업 폴더·/tmp 밖이나 너무 넓은 rm -r, DB·볼륨·migration 삭제를 막는다.
  셸 파서는 소유자 전역 guard_bash.py와 정의가 같은 사본이다. 사용자 전역
  설정에 guard_bash.py H12가 있으면 건너뛰어 두 번 막지 않는다.
- N4(PostToolUse Write·Edit): 비밀 값 모양을 몇 줄로 알리고 막지 않는다.
- 장부 SessionStart·Stop 훅: ~/.claude/harness/에 세션 기록 경로와 누적
  실측을 쓴다. 출력이 없어 컨텍스트 비용이 0이다.
- 스킬 estimate·retro·techdebt: 모두 모델이 부르고 발동 조건을 설명에
  문단으로 적었다(결정 Q9).
버린 대안: H12에 git reset --hard·clean·checkout -- .를 넣는 것(설계
5.1절). 이 기계 세션 기록의 Bash 명령 43,078개에서 정당한 사용이
61·32·31건이라 거짓 양성이 크다. 전역 훅을 플러그인으로 옮기는 것은
Q13대로 안정된 뒤에 한다.

위험: H12 판정이 전역 훅과 두 벌이다. 소유자 기계의 전역 훅 시험이 두
사본의 정의를 비교한다. 원격(ssh) rm은 작업 폴더를 몰라 너무 넓은
대상만 막는다.

검증:
- python3 -m unittest discover -s plugins/harness/tests: 17개 통과.
  조건을 하나씩 끈 사본 12개에서 모두 실패를 확인했다.
- 같은 판정을 이 기계 세션 기록 명령 43,078개에 돌려 5건이 막힘:
  의도한 막힘 3(desktop 작업 폴더 통째 rm 2, -p 없는 down -v 1),
  시험용 볼륨 rm 1, 당시 프로젝트 폴더를 알 수 없는 rm 1.
- claude plugin validate --strict: 마켓·플러그인 모두 통과.
- 로컬 경로 마켓으로 설치(--scope local) 뒤 새 세션에서 스킬 셋이 보이고
  SessionStart·Stop 훅이 기록을 썼다. 항상 드는 비용 약 698토큰.
2026-11-08 00:02:22 +09:00

89 lines
3.7 KiB
Python
Executable File

#!/usr/bin/env python3
"""이번 브랜치가 남긴 빚과 치울 것을 보여 준다(`techdebt` 스킬이 부른다). 아무것도 고치지 않는다.
python3 techdebt.py [--base <커밋>] 기준이 없으면 origin/main(없으면 main)과 갈라진 곳
보여 주는 것: diff가 더한 줄의 TODO·건너뛴 테스트·검사 끄기·디버그 출력, 추적하지 않는 파일,
지울 수 있는 worktree, 이미 합쳐진 로컬 브랜치.
"""
import argparse
import re
import subprocess
import sys
MARKERS = [
("할 일 표시", re.compile(r"\b(TODO|FIXME|XXX|HACK)\b")),
("건너뛴 테스트", re.compile(r"@Disabled\b|\.skip\(|\bx(it|describe)\(|@pytest\.mark\.skip|@unittest\.skip")),
("검사 끄기", re.compile(r"@SuppressWarnings|eslint-disable|@ts-ignore|@ts-expect-error|#\s*noqa|#\s*type:\s*ignore")),
("디버그 출력", re.compile(r"\bconsole\.log\(|System\.out\.println\(|\bdebugger;")),
]
MAX_PER_KIND = 20
def git(*args):
r = subprocess.run(["git", *args], capture_output=True, text=True)
return r.stdout if r.returncode == 0 else ""
def default_base():
for ref in ("origin/main", "main", "origin/master", "master"):
base = git("merge-base", "HEAD", ref).strip()
if base:
return base
return ""
def added_lines(base):
"""(파일, 줄 번호, 내용): base 이후 더한 줄. 커밋 안 된 변경도 포함한다."""
out, path, line_no = [], None, 0
for line in git("diff", "--unified=0", "--no-color", base).splitlines():
if line.startswith("+++ "):
path = line[6:] if line.startswith("+++ b/") else None
elif line.startswith("@@"):
m = re.search(r"\+(\d+)", line)
line_no = int(m.group(1)) if m else 0
elif line.startswith("+") and path:
out.append((path, line_no, line[1:]))
line_no += 1
return out
def main(argv):
p = argparse.ArgumentParser()
p.add_argument("--base")
args = p.parse_args(argv)
if not git("rev-parse", "--git-dir"):
print("git 저장소가 아니다.", file=sys.stderr)
return 1
base = args.base or default_base()
if not base:
print("기준 커밋을 찾지 못했다. --base로 준다.", file=sys.stderr)
return 1
print("기준: %s" % git("log", "-1", "--format=%h %s", base).strip())
found = {label: [] for label, _ in MARKERS}
for path, line_no, text in added_lines(base):
for label, pattern in MARKERS:
if pattern.search(text):
found[label].append("%s:%d %s" % (path, line_no, text.strip()[:100]))
for label, rows in found.items():
print("\n## %s (%d)" % (label, len(rows)))
print("\n".join(rows[:MAX_PER_KIND]) or "없음")
if len(rows) > MAX_PER_KIND:
print("… %d개 더" % (len(rows) - MAX_PER_KIND))
untracked = git("ls-files", "--others", "--exclude-standard").split()
print("\n## 추적하지 않는 파일 (%d)" % len(untracked))
print("\n".join(untracked[:MAX_PER_KIND]) or "없음")
prunable = [b for b in git("worktree", "list", "--porcelain").split("\n\n") if "\nprunable" in b]
print("\n## 지울 수 있는 worktree (%d)" % len(prunable))
print("\n".join(b.split("\n")[0] for b in prunable) or "없음")
current = git("branch", "--show-current").strip()
merged = [b.strip(" *+") for b in git("branch", "--merged", base).splitlines()]
merged = [b for b in merged if b and b != current and b not in ("main", "master")]
print("\n## 기준에 이미 합쳐진 로컬 브랜치 (%d)" % len(merged))
print("\n".join(merged[:MAX_PER_KIND]) or "없음")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))