코드를 변경한 후, 더 어려운 질문은 무엇이 바뀌었느냐가 아니라 그와 함께 무엇을 추가로 검토해야 하는가입니다. 프로젝트는 변경된 파일과 연결된 사양(specifications), 아키텍처 제약 조건(architectural constraints), 테스트를 간과하지 않도록 작업의 읽을 수 있는 흔적을 보존해야 합니다. Dotdotgod는 변경된 파일로부터 이러한 흔적을 역방향으로 읽어내는 graph impact를 일종의 **프로젝트 사이코메트리 (project psychometry)**로 취급합니다.

사람에 의해 유지되는 명시적인 프로젝트 메모리는 두 가지 경로를 생성합니다. 하나는 작업 시작 시 작업 목표에서 관련 문서로 이어지는 경로이고, 다른 하나는 작업 완료 후 변경된 파일에서 검토 범위로 이어지는 경로입니다.

프로젝트 메모리에는 두 가지 검색 방향이 있습니다

생명체는 현재의 신호를 사용하여 과거의 경험을 회상하고 다음에 무엇을 할지 결정합니다. 프로젝트 또한 현재의 목표나 이미 발생한 이벤트로부터 필요한 메모리를 검색할 수 있을까요? 이 글은 인지 과학의 엄격한 모델로서가 아니라, 설명을 위한 비유로서 인지(cognition)를 사용합니다.

작업 시작 시에는 원하는 결과가 검색 시드(retrieval seed)가 됩니다. 우리는 요청을 해석하고 관련 규칙, 사양, 아키텍처 및 과거의 결정 사항을 찾아냅니다. 작업이 끝난 후에는 변경된 파일이 시드가 됩니다. 우리는 결과를 검사하고 그와 함께 검토되어야 할 문서, 테스트 및 검증 명령어를 찾아냅니다.

작업 시작: 목표 및 요청 → 필요한 프로젝트 메모리
작업 종료: 변경된 파일 → 검토할 문서, 테스트 및 소스

Dotdotgod의 query는 자연어 질문에서 의미론적으로 관련된 문서로 이동함으로써 첫 번째 경로를 지원합니다. graph impact는 변경된 파일과 유지된 관계로부터 두 번째 경로를 생성합니다. 두 방식 모두 현재 읽어야 할 유지된 소스(maintained sources)의 범위를 좁혀줍니다.

유지된 흔적은 메모리의 원천입니다

픽션에서 사이코메트리(psychometry)는 물체에 남겨진 흔적으로부터 기억을 읽어내는 것을 말합니다. 프로젝트가 이와 유사한 기능을 제공하려면 먼저 읽을 수 있는 흔적이 필요합니다. Dotdotgod는 사람들이 읽고 편집할 수 있는 문서에 프로젝트 메모리를 보관합니다.

• 사양서(Specifications)는 제품이 현재 보장하는 동작을 설명합니다.
• 아키텍처 문서(Architecture documents)는 설계 근거(design rationale)와 제약 사항을 보존합니다.
• 테스트 문서(Test documents)는 무엇이 어떻게 검증되는지 설명합니다.
• README는 인덱스를 생성하고, 마크다운(Markdown) 링크를 통해 다음 문서로 가는 경로를 만듭니다.
• 추적성(Traceability)은 사양, 구현, 테스트 및 검증 명령을 명시적으로 연결합니다.

그래프 인덱스(Graph indexes)와 벡터 캐시(vector caches)는 이러한 소스들을 기반으로 구축된 파생된 검색 데이터입니다. 캐시가 삭제되더라도 유지 관리되는 프로젝트 메모리는 문서에 남아 있으며, 그래프 및 벡터 데이터는 문서와 리포지토리(repository) 구조로부터 다시 구축될 수 있습니다. 검색 결과는 소스 문서에 대한 주소를 제공하며, 그래프 점수(graph scores)는 검토 우선순위를 나타냅니다. 실제 동작은 관련 소스, 코드 및 테스트를 함께 조사함으로써 판단됩니다.

그래프 영향도(Graph Impact)는 역방향으로 흔적을 읽습니다

문서가 구현 및 테스트를 가리킬 때, 변경된 파일은 이러한 관계를 역방향으로 추적할 수 있습니다.

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

여러 파일이 하나의 변경 사항을 구성하는 경우 --changed를 반복합니다. 각 변경된 파일은 그래프 시드(graph seed)가 되며, 여러 시드가 공유하는 사양이나 테스트는 하나의 전체적인 검토 순위(review ranking)로 병합됩니다.

그래프는 사람들이 유지 관리하거나 리포지토리에서 결정론적(deterministically)으로 도출할 수 있는 관계를 사용합니다: 구조화된 추적성(traceability), 마크다운(Markdown) 링크, README 경로, 그리고 패키지 및 테스트 구조입니다. 기본 순위 산정 방식은 변경된 파일에 의해 시딩된 개인화된 페이지랭크(Personalized PageRank)를 추적성, 검증 신호(verification signals), 메모리 영역 정책(memory-area policy), 그리고 직접적인 근접성(direct proximity)과 결합합니다. semantic_similarity 관계 또한 경로, 파일 이름, 헤딩(headings), 패키지 이름을 통해 결정론적으로 계산됩니다. query는 별도의 자연어 임베딩(natural-language embedding) 검색을 사용합니다.

다음의 축약된 예시는 필수적인 출력 형태를 보여줍니다. 실제 경로, 점수 및 이유는 리포지토리 상태와 설정에 따라 달라집니다.

impact:
  changed_files:
    - packages/cli/src/commands/query.mjs
...

score는 후보를 조기에 검토하는 것의 가치를 나타냅니다. reasons는 구조화된 추적성 (traceability) 또는 직접적인 관계와 같이 후보가 나타나는 이유를 공개합니다. 결과를 문서 (documents), 테스트 (tests), 소스 파일 (source files), 명령 (commands)으로 그룹화하면 에이전트 (agent)에게 제한된 범위의 다음 작업 세트를 제공할 수 있습니다.

사이코메트리 (Psychometry) 비유의 한계

graph impact는 검토 후보 상위 항목의 제한된 목록을 반환합니다. 관련 항목이 결과에서 제외될 수 있으며, 높은 점수를 받은 파일의 수정 필요 여부는 연결된 소스 (sources)와 테스트 (tests)를 읽음으로써 결정됩니다.

결과 품질은 프로젝트가 보존하는 추적 (traces)의 품질에 달려 있습니다. 오래된 README 파일, 누락된 구현 관계 (implementation relationships), 그리고 많은 동작을 담당하는 대용량 파일들은 검토 범위를 더 넓고 덜 구체적으로 만듭니다. 명확한 문서 역할 (document roles), 추적성 (traceability), 그리고 현재 상태를 설명하는 테스트 관계 (test relationships)는 변경된 파일로부터 더 유용한 후보를 생성해냅니다.

graph impact 결과를 다음 검토 목록으로 사용하세요. 연결된 소스 (sources)와 테스트 (tests)를 확인한 후 최종 결정을 내리십시오.

변경 파일 (change files)
  → graph impact
  → 관련 소스 및 테스트 검토 (review related sources and tests)
...

사람들이 프로젝트 메모리를 유지합니다

사람들이 이해하기 쉬운 이름, 경로, 문서 역할, 그리고 관계는 AI에게도 인지적 단서 (cognitive cues)가 됩니다. 작업의 시작 단계에서는 목표 (goal)에서 필요한 소스 (sources)로 경로가 실행됩니다. 작업의 종료 단계에서는 변경된 파일 (changed files)에서 검토해야 할 소스 (sources)로 역방향으로 실행됩니다.

두 방향 모두 동일하게 유지 관리되는 소스 (sources)에서 시작됩니다. 사람들이 현재 상태에 맞게 문서와 추적성 (traceability)을 업데이트하면, 에이전트 (agent)의 검색 (retrieval) 및 변경 검토 (change-review) 경로도 함께 변화합니다.

프로젝트 사이코메트리 (Project psychometry)란, 사람들이 유지해 온 메모리 (memory)로부터 사람들이 놓칠 수 있는 다음 검토 경로를 읽어내는 능력입니다.

추가 읽기 (Further Reading)

• 프로젝트 구조가 AI를 위한 인지적 단서가 되는 방법 (Project Structure Becomes Cognitive Cues for AI)
• 문서 디렉토리는 AI 에이전트의 목차입니다 (A Documentation Directory Is an AI Agent's Table of Contents)
• Docs-First 프로젝트 메모리에서 벡터 검색 (Vector Search)의 역할 (The Role of Vector Search in Docs-First Project Memory)
• Graph Impact가 변경된 파일과 함께 검토할 항목을 찾는 방법 (How Graph Impact Finds What to Review Alongside a Changed File)
• Dotdotgod Query가 관련 문서를 찾는 방법 (How Dotdotgod Query Finds Related Documents)
• Graph Impact가 변경된 파일과 함께 검토할 항목을 찾는 방법 (How Graph Impact Finds What to Review Alongside a Changed File)
• Graph impact 명령 사양 (Graph impact command specification)
• Graph impact 품질 테스트 (Graph impact quality tests)