동작 방식

이 페이지는 report 뒤의 동작을 설명합니다. 무엇을 local 에서 수집하고, 무엇을 git note 로 남기며, 그 data 가 PR Report 와 Dashboard 에 어떻게 도착하는지 확인할 수 있습니다. Agent Note 를 쓰는 데 모든 세부사항을 외울 필요는 없지만, 결과가 예상과 다를 때 돌아올 model 입니다.

데이터 흐름

1. Promptcoding agent 에 요청한다

hooks 가 prompt 와 turn id 를 기록합니다.

→

2. EditAI 가 파일을 수정한다

hooks 또는 transcripts 가 변경된 file 과 attribution 에 쓰는 단서를 남깁니다.

→

3. Commitnote 를 기록한다

기록 가능한 session data 가 있을 때 git commit 이 trailer 를 넣고 git note 를 씁니다.

→

4. Share코드와 함께 공유한다

git push 로 refs/notes/agentnote 를 remote 로 보냅니다.

생성된 git hook 이 설치되어 있으면 대부분의 리포지토리에서는 평소처럼 git commit 과 git push 를 쓰면 됩니다. Cursor 는 local transcript 에서 prompt / response 쌍을 복원할 수 있고, git hook 을 쓸 수 없어도 shell hook 으로 commit 추적을 이어갈 수 있습니다.

저장소

레이어 1: 로컬 임시 데이터

.git/agentnote/sessions/ 안의 세션 데이터. prompt, 변경 내역, blob hash 를 담는 JSONL 파일입니다. 각 commit 뒤에 rotate 되며 push 되지 않습니다.

레이어 2: Git Notes

refs/notes/agentnote 안의 영구 기록. commit 당 하나의 JSON. push, fetch, 팀 공유가 가능합니다.

세션 파일

파일	목적
prompts.jsonl	turn 번호와 함께 한 줄에 하나의 prompt
changes.jsonl	AI 가 수정한 파일과 post-edit blob hash
pre_blobs.jsonl	각 AI edit 이전의 file 상태
heartbeat	세션 활동 시각
turn	prompt 마다 증가하는 단조 증가 카운터

Note 스키마

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "JWT auth middleware 구현",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "이전 response 가 이 middleware 를 바꿔야 하는 이유를 설명합니다." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "middleware 를 만들겠습니다...",
      "files_touched": ["src/auth.ts"],
      "tools": ["Edit"]
    }
  ],
  "files": [
    { "path": "src/auth.ts", "by_ai": true },
    { "path": "CHANGELOG.md", "by_ai": false }
  ],
  "attribution": {
    "ai_ratio": 73,
    "method": "line",
    "lines": { "ai_added": 146, "total_added": 200, "deleted": 12 }
  }
}

Attribution 방식

Claude Code

보통은 line-level 입니다. Agent Note 는 각 AI edit 전후의 file 상태를 비교하고, 나중에 들어간 human edit 를 final diff 에서 다시 빼서 계산합니다.

Codex CLI

처음에는 file-level 입니다. transcript patch count 가 final commit diff 와 맞을 때만 line-level 로 올라갑니다.

Cursor

처음에는 file-level 입니다. edit count 가 맞고 final file 이 마지막 AI edit 와 그대로 같을 때만 line-level 로 올라갑니다.

Gemini CLI

hook 과 transcript parsing 으로 prompt / response 와 file-level attribution 을 기록합니다. line-level 은 아직 없습니다.

📝 Context 를 수집하는 방식

📝 Context 는 continue 나 다음 작업으로 넘어가 같은 짧은 prompt 를 읽기 쉽게 만드는 표시 전용 보충 설명입니다. attribution 에는 영향을 주지 않습니다.

• reference context 는 바로 이전 response 에서 가져옵니다. final diff 에 포함된 file path, file 이름, code identifier 가 언급될 때만 사용합니다.
• scope context 는 현재 response 에서 가져옵니다. response 초반이 이번 작업 범위를 구체적으로 설명할 때만 사용합니다.
• Agent Note 는 yes, continue, お願いします 같은 짧은 승인 표현만으로 Context 를 선택하지 않습니다. file 이나 code 에 대한 구체적인 단서가 없으면 Context 를 붙이지 않습니다.
• Context 는 files_touched, prompt ownership, AI Ratio, attribution method, git note 저장 여부를 절대 바꾸지 않습니다.

Agent Note vs Entire

Agent Note 와 Entire 는 비슷한 문제를 다루지만 목표 workflow 가 다릅니다.

• Agent Note 는 git commit 과 그 commit 을 만든 AI 대화를 연결합니다. Entire 는 rewind / resume workflow 를 포함하는 더 넓은 checkpoint product 입니다.
• Agent Note 의 영구 record 는 refs/notes/agentnote 에 저장되고, 임시 session file 은 .git/agentnote/ 아래에 남습니다. Entire 는 checkpoint metadata 와 hosted web application 을 중심으로 합니다.
• Agent Note Dashboard 는 git notes 기반의 optional static GitHub Pages 입니다. hosted service 없이도 Agent Note 를 사용할 수 있습니다.
• Agent Note 는 과거 workspace state 를 복원하려는 tool 이 아닙니다. commit 이 왜 바뀌었는지, 어떤 prompt 가 관련됐는지, diff 중 어느 정도가 AI-authored 인지 review 하기 쉽게 만드는 데 집중합니다.

팁

prompt 목록은 session 전체가 아니라 commit 과 다음 commit 사이의 대화 window 에서 가져옵니다. Agent Note 는 현재 commit 을 설명하는 planning, clarification, review prompt 를 남기고, 인용된 과거 prompt 기록이나 이 commit 에 남지 않은 edit turn 은 잘라냅니다.

참고

대표적인 generated artifact 는 framework/cache path, generated filename/suffix, commit 된 file header 같은 구체적인 signal 로 best-effort 로 AI Ratio 분모에서 제외됩니다. build/, dist/, gen/, generated/, target/ 같은 범용 directory 이름만으로는 generated 로 보지 않습니다. Commit 에 남겨야 하는 bundle 이나 generated output 을 계속 표시하되 AI Ratio 에만 반영하지 않으려면 repository root 의 .agentnoteignore 에 적어 주세요.

세션 라이프사이클

이벤트	발생하는 일
SessionStart	세션 디렉터리를 만들고 heartbeat 를 기록
UserPromptSubmit	prompt 를 추가하고, turn counter 를 증가시키며, log 를 rotate
PreToolUse Edit/Write	pre-edit blob hash 를 동기적으로 캡처
PostToolUse Edit/Write	post-edit blob hash 와 file path 를 캡처
Stop	stop event 를 기록함 (heartbeat 는 계속 활성 상태 — Stop = response 끝, session 끝 아님)

참고

Plain Git hook 은 trailer 를 넣기 전에 fresh session 과 file evidence 를 요구합니다. 현재 Agent transcript 를 신뢰할 수 있으면, prompt 별 정확한 file touch 가 없어도 commit-level attribution 으로 남길 수 있습니다.

팁

Agent Note 는 현재 agent 를 인지합니다. 세션 메타데이터에 active adapter 가 저장되므로, 나중에 show, status, commit recording 이 올바른 transcript format 을 해석할 수 있습니다.

Git Notes

Git notes 는 branch 목록, GitHub UI, CI 에서는 보이지 않지만 push / fetch 는 가능합니다.

# 팀과 공유
git push origin refs/notes/agentnote

# remote 에서 가져오기
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# note 보기
git notes --ref=agentnote show <commit>

팁

agent-note init 이 auto-fetch 를 설정하고, pre-push hook 이 auto-push 를 처리합니다. 수동 명령은 필요하지 않습니다.