Touch Map (변경 영향 맵)

Touch Map

이 변경을 완료하기 위해 어떤 부분을 건드려야 하는지에 대한 정신적 지도를 구축합니다. 구현 계획을 작성하지 마세요. 코드를 작성하지 마세요. 파이프라인의 다음 스킬을 로드하지 마세요. 이후 워크플로우 스킬이 이 맵을 다른 스킬과 연결합니다.

맵이 곧 산출물입니다: 변경을 완료하는 데 필요한 부품과 파일.

사용 시점

사용자가 무엇을 변경할지, 그리고 이미 선택한 어떻게를 결정한 후에 로드합니다.

• 실행 대상: 새 기능, 버그 수정, 경계를 이동하는 리팩터링.
• 건너뛸 대상: 오타, 주석, 포맷팅, 락파일만 변경, 코드 없는 문서.
• 의도가 여전히 열려 있는 경우 ("X 구현"인데 선택된 동작이 없음): 중단하세요. 변경이 확정될 때까지 질문하세요. 그런 다음 맵을 작성하세요. 아직 선택되지 않은 기능에 대해 맵을 작성하지 마세요.

엄격한 제한 조건

1. 코드도, 다음 스킬도 안 됩니다. 이 스킬은 맵을 만듭니다. 블록을 계획하지 않습니다. 구현하지 않습니다.
2. 맵을 보여주고 중단합니다. 승인을 기다리지 마세요. 맵이 틀리면 사용자가 중단합니다.
3. coupling.json을 읽지 마세요. 그것은 나중의 별도 확인입니다.
4. 전체 저장소에서 유틸을 찾지 마세요. 에이전트가 적중 도메인에서 실제로 본 재사용만 기록하세요. 전체 검색은 이후 스킬이 담당합니다.

영속 아틀라스

경로: <repo>/.agent/domain-map.json

저장소에 커밋됩니다. 도메인 그레인만 포함합니다. 함수 이름은 여기에 속하지 않습니다.

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — 짧은 이름, 한 단어 또는 케밥-케이스.
• owns — 패키지 또는 폴더 경로.
• talksTo — 다른 도메인 id.

도메인 수준의 사실이 변경된 경우에만 이 파일을 작성합니다: 도메인이 추가, 제거 또는 이름이 변경된 경우; owns 경로; 또는 talksTo 링크. 기존 도메인 내부에 함수를 추가하는 경우 이 파일을 수정해서는 안 됩니다.

절차

절차 1: 확정된 의도 확인

1. 변경이 이미 명확하다면(명명된 버그, 명명된 함수, 명명된 동작), 계속 진행합니다.
2. 사용자가 여전히 원하는 것을 선택 중이라면, 맵 작성을 중단하세요. 의도가 확정될 때까지 질문하세요. 그런 다음 여기로 돌아옵니다.

절차 2: 아틀라스 로드 또는 부트스트랩

1. .agent/domain-map.json이 존재하면 읽습니다.
2. 파일이 없는 경우, 도메인 그레인만으로 첫 번째 아틀라스를 구축합니다:
   • packages/*(또는 저장소의 패키지 폴더)를 우선 사용합니다.
   • 그렇지 않으면 src/(또는 기본 소스 루트) 아래의 최상위 영역 폴더를 사용합니다.
   • owns 경로 간의 임포트 엣지를 기반으로 talksTo를 설정합니다.
   • 아틀라스에 함수 이름을 넣지 마세요.
3. 필요한 경우 .agent/를 생성합니다. 파일을 작성합니다. 같은 턴에 새 아틀라스를 보여줍니다. 계속 진행합니다. 기다리지 마세요.

절차 3: 이 변경에 집중

1. 아틀라스와 확정된 의도에서 적중 도메인을 선택합니다.
2. 명확하게 변경에 속하는 모듈에서 시작합니다.
3. 해당 파일을 읽습니다. "건드려야 할 파일" 목록이 계속 변경되는 동안에만 임포트를 따라갑니다.
4. 새로 연 파일이 맵을 변경하지 않을 때 중단합니다. 완전성을 위해 패키지를 읽지 마세요.
5. 부품을 변경이 사용하거나 옆에 위치할 모듈 및 기존 함수와 타입으로 명명합니다. 파일은 포인터일 뿐, 맵 자체가 아닙니다.
6. 해당 파일에서 실제로 본 재사용(경로 + 심볼)을 기록합니다. 전체 작업 공간에서 헬퍼를 grep하지 마세요.

절차 4: 둘 이상의 경로가 있는 경우 경로 선택

정직한 경로가 하나만 있다면, 한 줄로 명시합니다.

둘 이상의 경로가 있다면, 하나를 선택합니다. 다음 사다리 단계 중 결정하는 첫 번째 단계에서 멈춥니다:

1. 새 모듈을 작성하는 것보다 기존 것을 재사용합니다.
2. 적중 도메인 내에 머무릅니다. 새 도메인을 열지 마세요.
3. 내부 변경으로 동작한다면 패키지, 계층 또는 공개 API를 추가하지 마세요.
4. 그런 다음 가장 적은 파일을 선택합니다.

승자를 명명하고 어느 단계에서 결정했는지 명시합니다. 가장 적은 파일이 전체 규칙이 아니라 동점을 깨는 기준입니다. 파일 수에서 이기기 위해 신 파일에 새 동작을 밀어 넣지 마세요.

절차 5: 아틀라스 업데이트(도메인 수준만)

1. 이 변경이 도메인을 추가, 제거 또는 이름을 변경하거나, owns 또는 talksTo를 변경한다면, 같은 작업 내에서 .agent/domain-map.json을 패치합니다.
2. 도메인 그레인에서 변경된 것이 없다면, 파일을 그대로 둡니다.

절차 6: 변경별 맵 보여주기

이 여섯 개 섹션을 순서대로 보여줍니다. 작업별 마크다운 파일을 작성하지 마세요.

1. 적중 도메인 — 아틀라스에서.
2. 부품 — 모듈 및 관련된 기존 함수와 타입. 본 재사용(경로 + 심볼)을 포함합니다.
3. 상호 작용 방식 — 이 변경이 사용하는 엣지만(호출, 타입, 데이터). 전체 호출 그래프가 아닙니다. 엣지를 글머리 기호로 보기 어려운 경우에만 Mermaid 다이어그램을 추가합니다.
4. 건드려야 할 파일 — 완료 목록. 이것이 독립적인 산출물입니다.
5. 건드리지 않을 항목 — 명시적입니다. 엉뚱한 수정을 방지합니다.
6. 경로 선택 — 경로가 하나뿐이면 한 줄. 여러 경로가 있었다면 승자와 사다리 단계.

절차 7: 중단

1. 절차 6 이후에는 중단합니다.
2. 코드를 작성하지 마세요. 이 스킬에서 다른 스킬을 로드하지 마세요.

결정 트리

• 의도가 확정되지 않음 → 절차 1, 그런 다음 확정될 때까지 맵 작성을 중단.
• 의도 확정, 동작 변경 → 절차 2 → 3 → 4 → 5 → 6 → 7.
• 오타 / 주석 / 포맷 / 락파일 / 문서만 → 이 스킬은 적용되지 않음.
• 아틀라스 파일 없음 → 절차 2 단계 2(부트스트랩), 그런 다음 계속.
• 경로 하나 대 여러 경로 → 절차 4.

위험 신호

신호	의미	대신 할 일
사용자가 기능을 선택하기 전에 맵 작성	의도가 확정되지 않음	절차 1. 먼저 확실히 물어보세요.
owns의 모든 파일 열기	둘러보기, 맵이 아님	절차 3: 파일 목록이 안정화되면 중단.
모노레포에서 isRecord grep	전체 검색은 다른 스킬	이미 본 재사용만 기록.
coupling.json 읽기	잘못된 파일	그 확인은 나중에 맡기세요.
맵에 대해 "괜찮아 보이나요?" 기다리기	제한 조건은 보여주고 중단	여섯 섹션을 보여주고 중단.
맵 이후 코딩 시작	이 스킬은 맵만 작성	절차 7. 코드 금지.
여기서 다음 파이프라인 스킬 로드	구성을 워크플로우에 맡겨야 함	중단. 워크플로우 스킬이 순서를 정하게 하세요.
.agent/touch-maps/<task>.md 작성	쓸모없는 작업 쓰레기	채팅(또는 세션)만. 아틀라스 파일이 유일한 영속 파일.
헬퍼가 추가되었다고 아틀라스 수정	아틀라스에 함수 그레인	아틀라스는 그대로. 헬퍼를 섹션 2에 넣으세요.
가장 적은 파일로 경로 먼저 선택	신 파일 함정	전체 사다리를 실행하세요.

오류 처리

• git 저장소 내부가 아님: 여섯 섹션에서 이 변경을 맵으로 작성하세요. 아틀라스 파일은 건너뜁니다. 한 줄로 그 사실을 말하세요.
• 아틀라스 JSON이 유효하지 않음: 추측하지 마세요. 구문 분석 오류를 보고하세요. 사용자가 동의하는 경우에만 절차 2 단계 2에서 다시 빌드하거나, 의도가 명백한 경우(후행 쉼표, 누락된 대괄호) JSON을 수정하세요.
• 적중 도메인이 불명확함: 변경을 소유할 수 있는 가장 작은 도메인 집합을 선택하세요. 의심을 경로 선택에 명시하세요. 한 파일 버그에 대해 새 도메인을 만들지 마세요.
• 사용자가 맵이 틀리다고 중단: 여섯 섹션을 수정하세요. 경로가 변경된 경우 절차 4를 다시 실행하세요. 그런 다음 중단합니다.