task-view가 코딩 에이전트의 변경 사항을 지도처럼 보여준다

task-view는 코딩 에이전트가 만든 변경 사항을 평평한 diff 목록 대신, 각 부분이 어떻게 연결되는지 보여주는 지도로 검토하게 한다.

코딩 에이전트가 코드 대부분을 작성하면, 검토자는 바뀐 파일을 IDE에서 하나씩 열어 무엇이 무엇을 호출하는지, 요청이 어떤 경로를 거치는지, 각 부분을 어떤 테스트가 다루는지 머릿속으로 재구성해야 한다. diff는 바뀐 줄을 보여주지만 변경 사항의 구조는 검토자가 직접 파악해야 한다.

task-view는 그 구조를 한 페이지에 보여준다. 에이전트가 작업을 마치면 변경한 함수·컴포넌트·테스트와 변경 이유, 각 항목의 관계, 사용자가 경험하는 흐름을 설명한다. task-view는 이를 브라우저에서 볼 수 있는 페이지로 바꾼다. 페이지에는 변경 사항 그래프, 단계별 흐름, 각 부분의 코드와 에이전트가 밝힌 변경 이유가 함께 표시된다. 검토자는 구조를 다시 구성하는 대신 코드의 타당성을 판단하는 데 집중할 수 있다.

그래프 화면 이미지

task-view가 제공하는 기능은 다음과 같다.

• 변경된 함수·컴포넌트·엔드포인트·테스트의 관계를 저장소 여러 곳에 걸쳐 그래프로 표시한다. 무엇이 무엇과 연결되는지 머릿속에 담아 두지 않아도 된다.
• 변경 사항을 통과하는 각 경로를 진입점부터 경계까지 단계별로 보여준다. 해당 흐름을 실행하는 테스트는 검증하는 단계에 연결된다.
• 항목을 클릭하면 diff 또는 변경 후 코드를 읽을 수 있고, 에이전트가 밝힌 변경 이유와 관련 항목도 함께 볼 수 있다.
• 에이전트가 가리킨 파일·줄·커밋을 Git과 대조한다. 변경된 줄 가운데 에이전트가 설명하지 않은 부분도 diff 지도에 표시한다. 지도는 실제 diff와 일치하도록 검사하지만, 코드가 올바른지는 검토자가 판단해야 한다. 테스트 결과와 설명은 에이전트가 한 말로 표시된다.
• 작업마다 오프라인 HTML 파일 하나를 만들어 보관하거나 공유할 수 있다. 파일을 만들 때는 파일을 읽고 읽기 전용 Git 명령만 실행하며 테스트나 빌드 등 다른 도구는 실행하지 않는다.
• 프로그래밍 언어를 파싱하지 않는다. 파일·줄 범위·diff를 바탕으로 지도를 만들기 때문에 Go, TypeScript, Python, Rust, SQL, 설정 파일, 인프라 코드와 여러 언어 및 저장소에 걸친 변경에도 사용할 수 있다. 구문 강조는 약 300개 언어를 지원하고, 그 밖의 언어는 일반 텍스트로 표시한다.
• Claude Code, Codex 등 서면 지침을 따를 수 있는 코딩 에이전트와 함께 사용할 수 있다.

설치는 사용자 계정에만 적용되므로 sudo나 관리자 권한이 필요하지 않다. 실행 시 필요한 유일한 의존성은 git이다.

macOS와 Linux에서는 다음 명령으로 설치한다.

curl -fsSL https://raw.githubusercontent.com/gtindo/task-view/main/scripts/install.sh | sh

Windows PowerShell에서는 다음 명령을 사용한다.

irm https://raw.githubusercontent.com/gtindo/task-view/main/scripts/install.ps1 | iex

설치 스크립트(install.sh, install.ps1)는 시스템과 CPU에 맞는 바이너리를 최신 릴리스에서 받아 릴리스 체크섬과 대조한다. macOS에서는 격리 플래그를 해제하고, 필요하면 설치 폴더를 PATH에 추가한다. 바이너리는 ~/.local/bin에 설치하며 Windows에서는 %LOCALAPPDATA%\Programs\task-view에 설치한다. 설치 후 새 터미널을 열어야 한다. 업데이트할 때는 같은 설치 명령을 다시 실행한다. 버전을 고정하거나 실행 전에 스크립트를 읽는 방법은 사용자 안내서에 설명돼 있다.

직접 바이너리를 내려받아 설치할 수도 있다. 최신 릴리스에서 기기에 맞는 파일(task-view-darwin-arm64, task-view-darwin-amd64, task-view-linux-amd64, task-view-linux-arm64, task-view-windows-amd64.exe)을 받아 task-view로 이름을 바꾸면 된다. Windows에서는 task-view.exe로 바꾼다. 그런 다음 PATH에 포함된 폴더에 파일을 둔다. 정확한 명령은 사용자 안내서에 있다. Go를 쓰는 경우 go install github.com/gtindo/task-view/cmd/task-view@latest를 실행하거나 저장소를 내려받은 뒤 make install을 실행할 수 있다.

에이전트 설정과 검토 절차

빠른 시작 절차는 다음과 같다.

• task-view를 설치하고, 아래 세 가지 방법 가운데 하나로 에이전트에 한 번 형식을 알려준다.
• 에이전트에 작업을 맡긴다. 작업이 끝나면 에이전트는 .review/change-<task>.json을 작성하고, 계정이 검증을 통과할 때까지 task-view validate로 검사한다.
• 에이전트가 알려주는 명령으로 검토 페이지를 연다. 예를 들면 다음과 같다.

task-view open .review/change-<task>.json

문제가 있어 보이면 에이전트에 코드나 계정을 수정해 달라고 요청한 뒤 open을 다시 실행한다.

에이전트에 지침을 알려주는 방법으로는 skill 사용을 권장한다. skills/task-review/SKILL.md는 바로 쓸 수 있는 skill 파일이다. 작업이 끝나면 에이전트가 task-view instructions를 실행하고 출력된 지침을 따르도록 안내한다. 따라서 지침은 설치된 바이너리의 형식과 항상 일치한다. Claude Code에서는 파일을 저장소 안에 복사하거나, 모든 저장소에서 쓰도록 ~/.claude/skills/에 둘 수 있다.

mkdir -p .claude/skills/task-review
curl -fsSL https://raw.githubusercontent.com/gtindo/task-view/main/skills/task-review/SKILL.md -o .claude/skills/task-review/SKILL.md

name과 description 프런트매터가 있는 SKILL.md를 읽는 에이전트라면 같은 파일을 사용할 수 있다. 이 파일은 모든 릴리스에도 포함된다.

다른 방법은 지침을 저장소의 문맥 파일로 두는 것이다. 다음 명령으로 지침을 TASK_REVIEW.md에 저장한다.

task-view instructions > TASK_REVIEW.md

그런 다음 해당 저장소의 AGENTS.md(Codex 및 대부분의 에이전트) 또는 CLAUDE.md(Claude Code)에 다음 한 줄을 추가한다.

When you finish a task, follow TASK_REVIEW.md.

task-view를 업그레이드한 뒤에는 파일을 새로 만든다.

별도의 설정 없이 일회성 프롬프트로 요청할 수도 있다. 작업 프롬프트 끝에 다음 문장을 붙인다.

When you're done, run `task-view instructions` and write a review file for
this task.

이미 커밋된 작업에도 같은 방법을 쓸 수 있다.

Run `task-view instructions` and write `.review/change-<name>.json` for
commit `<sha>`. Don't change any code.

검토 페이지와 검증

페이지는 같은 변경 사항을 그래프, 흐름, diff 지도, 주장이라는 네 가지 방식으로 보여주며, 항목을 클릭하면 상세 정보를 보는 패널이 열린다. 각 항목에는 코드에 대한 참조가 실제 변경 사항에 근거하는지, 아니면 에이전트의 설명에만 의존하는지도 표시된다.

항목의 채우기 색은 변경 상태를 나타낸다. 추가된 코드는 초록색, 수정된 코드는 파란색, 삭제된 코드는 빨간색이며, 바뀌지 않은 항목은 윤곽선으로만 표시된다. 측면 패널에는 에이전트의 요약, 각 저장소의 기준 커밋부터 최종 상태까지의 커밋, 발견 사항, 에이전트의 메모가 항상 나온다.

아래 화면 예시는 에이전트가 설명한 이 저장소의 실제 커밋 하나를 검토한 결과다.

그래프는 페이지 상단에서 변경 사항 전체를 한눈에 보여준다. 소스 코드 노드는 저장소별로 묶이고 저장소 사이의 엔드포인트는 서로 연결된다. 테스트·문서·변경되지 않은 노드는 도구 모음의 스위치로 표시 여부를 바꿀 수 있다. /를 눌러 검색하고 노드를 클릭하면 해당 노드와 이웃 노드에 초점을 맞출 수 있다.

노드·연결선·변경 구간·발견 사항을 클릭하면 오른쪽에 상세 패널이 열린다. 패널에서는 항목의 위치, 에이전트가 설명한 변경 이유, 이를 다루는 테스트, 다른 노드와의 관계, 코드를 볼 수 있다. 코드 상자는 변경된 줄과 대체된 내용을 보여주는 Diff 보기와 변경 후 코드를 보여주는 After 보기 사이에서 전환할 수 있다.

상세 패널 화면 이미지

흐름 화면은 변경 사항을 통과하는 사용자 또는 호출자 관점의 경로마다 한 개의 가로 트랙을 만든다. 각 경로는 왼쪽에서 오른쪽으로 이어지고, 경로의 단계를 검증하는 테스트는 해당 단계 아래에 배치된다.

흐름 화면 이미지

diff 지도는 변경된 모든 파일을 각 변경 구간의 막대로 보여준다. 어떤 노드가 해당 구간을 설명하는지에 따라 색을 나눈다. 초록색은 설명된 구간, 호박색은 일부만 설명된 구간, 빨간색은 전혀 언급되지 않은 구간이다. 이 화면에서 빠진 변경 사항이 없는지 확인할 수 있다.

diff 지도 화면 이미지

주장 화면에는 검토자가 의심할 수 있는 진술을 표시한다. 예를 들어 “탭 상태가 새로고침 뒤에도 유지된다”는 주장과 그 근거를 함께 볼 수 있다. 근거 항목을 펼치면 가리키는 정확한 코드나 커밋이 나온다.

주장 화면 이미지

검토 파일에 오류가 남아 있으면 페이지에 빨간 배너가 표시되고 측면 패널의 발견 사항에 검증되지 않은 내용이 나열된다. 예시에는 해당 줄에 없는 텍스트를 가리키는 연결선과 어떤 노드도 언급하지 않은 변경 CSS 줄이 있다.

발견 사항 화면 이미지

안내서와 명령

주요 명령은 다음과 같다.

검토 파일에 적힌 저장소만 읽는다. --scan-siblings를 사용하면 해당 저장소와 나란히 있는 폴더도 살펴보고, 검토 파일에 포함되지 않았지만 미커밋 변경 사항이 있는 Git 저장소를 unlisted_repo 경고로 알린다.

작동 방식과 범위

작업 흐름은 다음과 같다.

flowchart LR
 A["Agent finishes<br/>the task"] --> W["Writes<br/>.review/change-#lt;task#gt;.json"]
 W --> V{"task-view<br/>validate"}
 V -- "findings with hints" --> F["Agent fixes<br/>the account"]
 F --> V
 V -- "exit 0" --> O["task-view open"]
 O --> R["You review<br/>the page"]
 R -. "ask for a revision" .-> A

• 에이전트가 계정을 작성한다. .review/change-<task>.json에는 대상 저장소와 커밋, 변경 사항에서 의미 있는 부분마다 하나씩 노드가 들어간다. 노드는 함수·컴포넌트·설정 블록·테스트 사례 등이 될 수 있다. 파일은 노드 사이의 연결, 노드가 이루는 흐름, 정확한 줄이나 커밋을 가리키는 주장을 담는다.
• 에이전트가 계정을 검증한다. task-view validate --format json은 스키마, 커밋 체인, 모든 참조, diff 범위의 설명 여부를 검사한다. 각 오류나 경고에는 에이전트가 조치할 수 있는 힌트가 붙는다. 예를 들어 잘못된 줄 범위, 해당 줄에 없는 텍스트, 어떤 노드도 설명하지 않은 변경 줄을 알려준다. 에이전트는 파일이 검증을 통과할 때까지 이 절차를 반복한다.
• 검토자가 페이지를 연다. task-view open은 같은 검사를 수행하고 파일에 적힌 저장소만 읽은 뒤 .review/generated/change-<task>.html에 페이지를 만든다. 작업마다 파일이 따로 만들어지므로 이전 검토 파일도 .review/에 남는다.

이 검사는 검토 페이지의 지도가 실제 diff와 일치하는지 확인하기 위한 것이다. 작업이 잘됐는지는 검사하지 않으며, 페이지는 검토자가 이를 판단하도록 돕는다. 도구는 파일을 읽고 짧은 목록의 읽기 전용 Git 명령만 실행한다. 페이지에 표시되는 테스트 결과는 언제나 에이전트의 설명이다.

개발과 관련해 make test는 생성된 테스트용 저장소에서 단위 테스트와 골든 테스트를 실행하고, make build는 bin/task-view를 만든다. make check는 vet, lint(golangci-lint, npx를 통한 ESLint), 테스트를 실행한다. 코드 규칙과 패키지 경계는 AGENTS.md에 있다.

코드 구성은 다음과 같다. cmd/task-view는 CLI, internal/review는 모델·내장 JSON Schema·구조 규칙, internal/engine은 Git 상태·diff·참조 및 범위 검사, internal/render는 화면 데이터와 내장 페이지를 담당한다. 내장 페이지에는 assets/app.js, assets/app.css, 벤더링된 Cytoscape.js와 ELK가 포함된다. internal/langs는 Chroma 렉서와 구문 강조, internal/instructions는 TASK_REVIEW.md, internal/fixture는 테스트용 저장소, scripts/는 설치 스크립트, skills/는 에이전트 skill, docs는 사용자 안내서·스크린샷·make docs로 다시 생성되는 TASK_REVIEW.md 사본을 담는다.

정확한 검토 사례의 골든 출력은 cmd/task-view/testdata/valid.golden.json에 있다. make golden으로 갱신할 수 있다.

릴리스는 버전 태그를 푸시할 때만 .github/workflows/release.yml이 만든다. main에 푸시해도 릴리스가 만들어지지 않는다. 워크플로는 vet과 테스트를 실행한 뒤 Linux(amd64, arm64), Windows(amd64), macOS(Intel, Apple silicon)용 make release를 수행하고, 바이너리·SHA256SUMS·안내서·skill을 GitHub 릴리스로 공개한다. v0.2.0-rc.1처럼 접미사가 붙은 태그는 프리릴리스로 표시된다.

git tag v0.2.0
git push origin v0.2.0

make release VERSION=0.2.0을 실행하면 같은 release/ 폴더를 로컬에서 만들 수 있다.

task-view는 개인용 도구이자 하루 만에 만든 초기 아이디어이며, 제작자는 이슈나 풀 리퀘스트를 받지 않는다고 밝혔다. 대부분의 작업 흐름에 맞지만 다른 기능을 원한다면 포크할 수 있다. 자체 에이전트가 안전하게 도구를 바꿀 수 있도록 사양(specs/init.md), 코드 규칙(AGENTS.md), 골든 테스트가 제공된다.

task-view는 MIT License로 배포된다. 페이지에는 Cytoscape.js와 cytoscape-elk(MIT), ELK(Eclipse Public License 2.0)가 포함된다. 이들의 라이선스는 internal/render/assets/vendor/LICENSES.txt에 있으며, 모든 릴리스에 THIRD_PARTY_LICENSES.txt로 포함된다.