시맨틱 검색 (Semantic search)은 자연어 질문과 관련된 문서를 찾을 수 있습니다. 구현 변경 후에는 어떤 사양서(specifications), 아키텍처 노트(architecture notes), 테스트(tests), 그리고 검증 명령(verification commands)을 변경된 파일과 함께 검토해야 하는지가 핵심 질문이 됩니다. dotdotgod graph impact는 변경된 파일에서 시작하여 명시적인 이유와 함께 제한된 검토 목록을 생성하며, 문서의 목차(table of contents)를 변경 사항에서 유지 관리되는 소스로 되돌아가는 역방향 맵(reverse map)으로 사용합니다.

파일명 검색만으로는 이 질문에 답하기 어렵습니다. 코드와 문서는 서로 다른 이름을 사용할 수 있으며, 하나의 변경 사항이 여러 패키지 및 검증 경로와 연결될 수 있기 때문입니다.

필수적인 토대는 사람들이 직접 검토하고 유지 관리할 수 있는 프로젝트 메모리(project memory)입니다. 사양서, 아키텍처 노트, 테스트 문서, README 인덱스, 그리고 추적성 관계(traceability relationships)가 저장소(repository)에 남아 있으므로, 사람과 에이전트가 동일한 증거를 읽고 업데이트할 수 있습니다. Graph impact는 이러한 유지 관리 가능한 소스로부터 다음 검토 경로를 계산합니다.

변경된 파일을 그래프 시드(Graph Seeds)로 사용하기

단일 변경 파일에 대해 다음 명령어를 사용하여 관련 항목을 찾으세요:

dotdotgod graph impact . \
  --changed packages/cli/src/commands/query.mjs \
  --yml

여러 파일이 동일한 변경 사항에 속하는 경우 --changed를 반복합니다:

dotdotgod graph impact . \
  --changed packages/cli/src/commands/query.mjs \
  --changed packages/cli/src/query/chunks.mjs \
...

이 명령어는 처음 발견된 순서대로 경로의 중복을 제거하며, 동일한 가중치를 가진 최대 20개의 고유한 변경 파일 시드(seeds)를 허용합니다. 변경된 파일이 가장 먼저 나타나며, 여러 시드에 연결된 항목은 하나의 순위로 병합됩니다. 이를 통해 전체 변경 사항에 걸쳐 중요한 사양서와 테스트를 찾아낼 수 있습니다.

그래프 관계는 유지 관리되는 프로젝트 증거로부터 생성됩니다

프로젝트 그래프는 사람들이 유지 관리하는 관계 또는 리포지토리(repository) 구조가 결정론적으로 노출하는 관계로부터 구축됩니다. query가 리포지토리 전반의 의미론적 유사도 검색 (semantic similarity search)을 처리한다면, 그래프 임팩트 (graph impact)는 검토 근거 (review rationale)를 추적할 수 있는 연결 관계를 사용합니다. 그래프는 이러한 증거로부터 파생된 지도이며, 팀은 마크다운 (Markdown) 소스와 추적 가능성 (traceability) 정보를 검토함으로써 관계의 정확성을 직접 관리합니다.

사람이 작성한 추적 가능성은 경로(paths)나 이름으로부터 추론된 라우팅 힌트 (routing hints)보다 신뢰도가 높습니다. 명시적인 연결이 부족할 때는 README 파일과 안정적인 프로젝트 용어들이 보조적인 탐색 경로를 제공합니다.

따라서 그래프 임팩트의 품질은 그래프 알고리즘과 유지 관리되는 프로젝트 증거의 상태 모두에 달려 있습니다. 사양서 (specifications)와 테스트가 실제 구현 (implementation)을 가리키고, README 파일이 현재 문서로 연결되며, 파일의 책임 범위가 좁을수록 결과는 더욱 구체화됩니다.

검토 가치에 따른 순위 지정 (Rank by Review Value)

모든 관련 노드 (node)를 반환한다면 임팩트 분석은 또 다른 리포지토리 전반의 검색 기능으로 전락할 것입니다. 기본 balanced 정책은 변경된 파일에 의해 시드 (seed)가 설정된 개인화된 페이지랭크 (Personalized PageRank, PPR)와 프로젝트 검토 정책을 결합합니다.

변경된 파일 (changed files)
  → 후보 범위 제한 (bound the candidate scope)
  → 멀티 시드 개인화된 페이지랭크 (multi-seed Personalized PageRank)
...

기본 점수는 변경된 파일로부터 계산된 PPR로 시작합니다. 명시적인 추적 가능성, 테스트 및 검증 신호, 그리고 마크다운 링크와 README 파일을 통한 직접적인 근접성이 가중치를 더합니다. 경로, 헤딩 (headings), 메모리 영역 (memory areas) 또는 패키지 이름 (package names)이 일치할 경우 결정론적 라우팅 힌트가 보조 신호로 작용합니다.

메모리 정책 (Memory policy)은 현재 영역 (area)의 우선순위와 해당 영역의 fresh 또는 stale 분류를 적용한 다음, 아카이브 본문 (archive bodies)에 페널티를 부여합니다. 첫 번째 화면은 신뢰도가 낮은 라우팅 전용 항목보다 추적 가능성 (traceability), 테스트, 그리고 직접적인 근접성 (direct proximity)을 우선시합니다. 실행 가능한 파일이 충분히 존재하면, 의존성 (dependencies)과 같이 실행 가능성이 낮은 메타데이터는 결과에서 제외됩니다.

기본 정책은 아카이브 본문보다 현재의 사양 (specifications) 및 검증 경로 (verification routes)를 우선시합니다. 여기서 fresh와 stale은 파일 수정 시간과는 무관한 메모리 영역 (memory-area) 분류입니다.

결과는 이유가 포함된 검토 목록입니다

--yml은 에이전트가 직접 읽을 수 있는 제한된 구조를 반환합니다. 다음 예시는 출력 형태를 보여주며, 실제 경로, 점수 (scores), 그리고 이유 (reasons)는 저장소 (repository)의 상태와 설정에 따라 달라집니다.

impact:
  ok: true
  changed_files:
...

결과는 문서, 동작 계약 (behavior contracts), 테스트, 파일, 명령 (commands), 그리고 패키지 리소스 (package resources)를 그룹화합니다. score와 reasons는 각 포함 항목에 대한 설명을 제공하며, 누락된 항목 수 (omitted-item counts)는 제한된 출력 범위를 벗어난 후보들을 나타냅니다.

기본 출력 또는 --compact 옵션은 사람이 빠르게 읽기에 적합합니다. 에이전트 워크플로우에는 --yml을 사용할 수 있으며, --json은 상세한 점수와 자동화 진단 정보를 제공합니다.

Graph Impact와 벡터 검색 (Vector Search)의 역할 차이

dotdotgod query는 자연어 질문에 의미론적으로 가까운 문서를 찾습니다. Graph impact는 유지 관리되는 관계를 통해 변경된 파일과 연결된 검토 항목을 찾습니다.

기본적인 그래프 임팩트 (graph impact) 순위 산정에는 임베딩 유사도 (embedding similarity)를 사용하지 않습니다. 경로, 헤딩 (headings), README 파일, 메모리 영역 (memory areas), 그리고 패키지 메타데이터 (package metadata)를 통한 어휘적 라우팅 (Lexical routing)은 결정론적 (deterministically)으로 계산됩니다. 임베딩 검색 (Embedding search)과 그래프 인덱스 (graph index)는 별도의 캐시 (cache)와 장애 경계 (failure boundaries)를 가집니다.

이러한 분리는 결과의 설명 가능성 (explainable)을 유지해 줍니다. 각 결과는 의미론적 유사성 (semantic similarity)에서 기인했는지, 아니면 구현 및 테스트 관계, README 경로, 그리고 기타 유지 관리되는 증거로부터 기인했는지 식별될 수 있습니다.

높은 점수는 검토 우선순위 신호입니다

임팩트 점수가 높을수록 해당 항목을 조기에 검토하는 것이 더 큰 가치를 지님을 나타냅니다. 점수가 파일의 오류 여부를 결정하는 것은 아니며, 영향을 받는 항목이 제한된 결과 범위 밖에 남아 있을 수도 있습니다.

추적 가능성 (traceability)이 희소하거나 여러 동작을 소유한 대형 파일은 더 광범위한 결과를 생성합니다. 그래프 임팩트가 경로를 식별한 후에는, 사양 (specifications)을 읽고, 구현 및 테스트를 업데이트하며, 회귀 테스트 (regressions)를 실행하고, 링크와 추적 가능성이 여전히 현재 상태를 가리키고 있는지 확인하십시오.

파일 변경
  → graph impact 실행
  → 관련 사양 및 테스트 검토
...

그래프 캐시 (graph cache) 또한 파생 데이터 (derived data)입니다. 그래프 명령은 캐시가 누락되었거나 오래된 경우 저장소 파일로부터 이를 갱신하지만, 소스 사양과 코드는 판단의 근거로 유지됩니다.

예상 결과에 따른 임팩트 품질 측정

점수가 계산된 이유를 설명하고 진정으로 유용한 파일을 상단에 배치하는 것 모두 검증을 필요로 합니다. dotdotgod은 대표적인 사례에 대해 체크인된 예상 결과 (expected results)와 그래프 임팩트 순위를 비교 평가합니다.

평가 스크립트는 현재 결과와 베이스라인 (baseline)을 비교하여 판결을 반환합니다. 실제 사례가 축적됨에 따라, 이러한 측정값은 프로젝트에 적합한 CI 임계값 (thresholds)을 선택하기 위한 근거를 제공합니다.

변경 검토는 역 목차 (Reverse Table of Contents)에서 시작됩니다

문서 목차 (Table of Contents)는 제품에 대한 질문으로부터 관련 사양 (specifications) 및 테스트 (tests)로 이어지는 순방향 지도 (forward map)입니다. Graph impact는 코드 및 문서 변경 사항으로부터 함께 검토되어야 할 섹션들로 거슬러 올라가는 역방향 지도 (reverse map)입니다.

두 방향을 연결함으로써, 변경 사항이 발생한 후에도 사양 (specifications), 구현 (implementation), 그리고 테스트 (tests)가 동일한 프로젝트 상태를 계속해서 설명할 수 있게 합니다. 핵심적인 속성은 탐색 지도 (navigation map)가 자동으로 계산되더라도, 그 근거는 사람들이 읽고 수정할 수 있는 문서와 관계 (relationships) 속에 남아 있다는 점입니다. 팀이 이러한 소스들을 유지 관리하면, 에이전트 (agent)의 검토 경로 (review routes)도 함께 업데이트됩니다.

Graph impact는 사람이 직접 관리하는 프로젝트 메모리 (project memory) 내에서 자칫 놓칠 수 있는 검토 경로 (review routes)를 찾아냅니다. 최종적인 영향도 결정은 연결된 소스들과 테스트를 함께 검토함으로써 이루어집니다.

추가 읽기 (Further Reading)

• AI Agent Memory Starts with a Documentation Table of Contents
• How dotdotgod Maintains a Documentation Table of Contents
• Why Project Memory Should Stay Docs-First Even with Vector Search
• How dotdotgod Query Finds Relevant Documents from a Natural-Language Question
• Graph Impact Command Specification
• Impact Ranking Configuration
• Graph Impact Quality Tests