tc-tracker

tc-tracker skill 개요

tc-tracker의 용도

tc-tracker는 구조화된 Technical Change 추적을 위한 엔지니어링 skill입니다. 프로젝트의 docs/TC/ 아래에서 AI agent가 JSON 변경 기록을 생성, 업데이트, 검증, 재개, 종료할 수 있게 돕습니다. 채팅 기억, 흩어진 메모, 커밋 메시지에 의존하는 대신 무엇이 바뀌었는지, 왜 바뀌었는지, 영향을 받은 파일, 테스트 근거, 상태, blocker, 세션 handoff 맥락을 기록합니다.

잘 맞는 사용자와 프로젝트

tc-tracker skill은 여러 채팅, handoff, 리뷰 사이클에 걸쳐 진행될 수 있는 AI 코딩 세션을 사용하는 팀에 특히 잘 맞습니다. 구현 작업을 이슈처럼 추적해야 하거나, 코드 변경에 대한 감사 추적이 필요하거나, feature, bugfix, refactor, infrastructure, documentation, hotfix, enhancement 작업 전반에서 반복 가능한 상태 요약이 필요할 때 유용합니다.

Issue Tracking 관점의 핵심 차별점

tc-tracker는 일반적인 “issue tracker를 만들어줘”식 프롬프트와 달리 구체적인 저장 구조, TC ID 규칙, append-only revision history 모델, 검증 스크립트, lifecycle state machine을 함께 제공합니다. GitHub Issues나 Jira를 대체하는 도구라기보다는, 코드 파일, 테스트, 의사결정, AI handoff 메모를 연결하는 repository-local 구현 로그에 가깝습니다.

tc-tracker를 쓰지 않는 편이 나은 경우

단순 오타 수정, 포맷팅만 바꾸는 작업, git history에서 일회성 changelog를 생성하는 용도라면 tc-tracker는 피하는 것이 좋습니다. 이미 성숙한 이슈 워크플로를 강하게 운영하고 있고 repository에 추가 JSON 기록을 두고 싶지 않은 프로젝트에도 다소 무거울 수 있습니다.

tc-tracker skill 사용 방법

tc-tracker 설치와 먼저 읽을 파일

호환되는 skills 환경에서 다음 명령으로 skill을 설치합니다.

npx skills add alirezarezvani/claude-skills --skill tc-tracker

그다음 source directory인 engineering/skills/tc-tracker를 확인합니다. agent trigger 규칙과 workflow는 SKILL.md를 먼저 읽고, script 예시는 README.md를 확인한 뒤, references/lifecycle.md, references/tc-schema.md, references/handoff-format.md를 읽으세요. scripts/ 안의 Python helper는 단순 예시가 아니라 실제 워크플로에서 바로 쓰는 실용적인 자산입니다.

프로젝트에서 tracking 초기화하기

tc-tracker의 핵심 사용은 repository-local tracking 영역을 만드는 것에서 시작합니다.

python3 scripts/tc_init.py --project "My Project" --root .

이 명령은 configuration, registry, records, evidence 위치를 포함한 docs/TC/를 생성합니다. initializer는 idempotent이므로 다시 실행해도 설정을 중복 생성하지 않고 기존 상태를 보고해야 합니다. 대상 프로젝트 루트에서 실행하거나 --root /path/to/project를 명시적으로 전달하세요.

Technical Change 생성 및 업데이트

처음부터 좋은 프롬프트를 주면 agent가 추측하지 않고 유효한 record를 만들 수 있습니다.

Use tc-tracker to create a TC for adding JWT authentication. Project root is .. Scope is feature, priority is high. Summary: add login endpoint, JWT signing, and auth middleware. Motivation: protected API routes need authenticated access. Initial files likely affected: src/auth.py, src/middleware.py, tests/test_auth.py.

이에 해당하는 script 흐름은 다음과 같습니다.

python3 scripts/tc_create.py --root . \
  --name "user-auth" \
  --title "Add JWT authentication" \
  --scope feature --priority high \
  --summary "Adds JWT login endpoint, signing, and middleware" \
  --motivation "Required for protected API endpoints"

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --set-status in_progress --reason "Starting implementation"

작업이 진행되면 끝까지 기다렸다가 한꺼번에 정리하지 말고, 영향을 받은 파일, 테스트 케이스, 의사결정, 상태 변경을 계속 추가하세요.

handoff와 status 명령을 제대로 활용하기

tc-tracker를 가장 가치 있게 쓰는 습관은 세션이 끝나기 전에 유용한 handoff를 남기는 것입니다. 구체적인 진행 상황, 바로 실행할 수 있을 만큼 작은 다음 단계, blocker, 의사결정, 진행 중인 파일을 포함하세요.

python3 scripts/tc_update.py --root . --tc-id <TC-ID> \
  --handoff-progress "Implemented JWT signing and wired middleware into router" \
  --handoff-next "Add integration test for invalid token returning 401" \
  --handoff-blocker "Need final test fixture shape for user records"

작업 상태는 다음으로 확인합니다.

python3 scripts/tc_status.py --root . --all
python3 scripts/tc_validator.py --root .

재개용 프롬프트에서는 agent에게 docs/TC/records/<TC-ID>/tc_record.json, 특히 session_context.handoff를 읽고 기록된 다음 단계부터 이어서 진행하라고 요청하세요.

tc-tracker skill FAQ

tc-tracker는 완전한 issue tracker인가요?

아닙니다. Issue Tracking 용도의 tc-tracker는 repository-local이며 변경 작업에 초점을 둡니다. 구현 상태, 파일, 테스트, 의사결정, handoff 맥락을 추적합니다. 팀 배정, 토론, labels, boards, 외부 stakeholder 워크플로에는 GitHub Issues, Linear, Jira를 사용하세요.

일반 프롬프트보다 나은 점은 무엇인가요?

일반 프롬프트도 작업을 요약할 수는 있지만, 보통 schema, lifecycle transition, append-only revision, 반복 가능한 directory layout을 강제하지는 않습니다. tc-tracker는 AI agent가 변경 기록을 생성, 업데이트, 검증, 목록화할 수 있는 지속 가능한 format과 script를 제공합니다.

tc-tracker는 초보자에게도 적합한가요?

Python script를 실행하고 JSON 파일을 commit하는 데 익숙하다면 그렇습니다. 초보자는 README.md의 quick-start 명령부터 시작하고, references/tc-schema.md와 references/lifecycle.md를 이해하기 전까지는 TC JSON을 직접 편집하지 않는 것이 좋습니다.

도입을 가로막는 요소는 무엇인가요?

가장 큰 도입 비용은 프로세스 부담입니다. 의미 있는 변경마다 TC record, status update, 좋은 handoff text가 필요합니다. 팀이 이 record를 꾸준히 관리하지 않으면 registry가 낡은 상태가 될 수 있습니다. 이 skill은 TC update가 나중에 덧붙이는 일이 아니라 코딩 workflow의 일부일 때 가장 잘 작동합니다.

tc-tracker skill 개선 방법

tc-tracker에 더 좋은 입력 제공하기

tc-tracker는 프롬프트에 project root, change goal, scope, priority, motivation, 예상 파일, test expectation, 현재 불확실성이 포함될 때 가장 잘 작동합니다. 약한 입력은 “track auth work”입니다. 강한 입력은 “create a high-priority feature TC for JWT auth, affecting these files, with tests for valid token, invalid token, and missing token.”처럼 구체적입니다.

lifecycle transition을 현실적으로 유지하기

state machine을 지키세요: planned, in_progress, blocked, implemented, tested, deployed. test evidence 없이 TC를 tested로 표시하지 말고, 초기 planning 단계에서 곧바로 deployed로 건너뛰지 마세요. 작업이 되돌아갔다면 이유와 함께 in_progress로 다시 이동하세요.

각 세션 뒤 handoff 품질 높이기

가장 흔한 실패 방식은 handoff text가 모호한 것입니다. “finish tests” 대신 “Add tests/test_auth.py::test_expired_token_returns_401 and run pytest tests/test_auth.py -q.”처럼 구체적인 행동으로 바꾸세요. blocker는 실제로 진행을 막고 있을 때만 포함하고, 다음 AI session이 같은 논의를 반복하지 않도록 의사결정에는 근거를 함께 기록하세요.

validation과 review로 반복 개선하기

첫 output 이후 status와 validator script를 실행한 다음, 누락된 field, 잘못된 transition, 오래된 file list, 약한 test evidence를 agent에게 수정하게 하세요. 장기적으로 더 좋은 결과를 얻으려면 references/tc-schema.md를 검토하고, 모든 TC가 종료되기 전에 review-ready summary, affected files, test cases, session context를 포함하도록 프롬프트를 다듬으세요.