프로젝트 논리 맵
유지보수자와 AI가 다음 질문에 답할 수 있도록 돕습니다: 무엇을 바꿀 것인가, 어디에 영향을 미치는가, 무엇을 망가뜨리면 안 되는가, 어떻게 검증할 것인가.
작업 범위 선택
- 최초 생성: 요구사항과 코드 포렌식을 통해 Markdown 관계 맵을 생성합니다. 사용자가 시각적 탐색을 원하거나 이미 HTML이 있는 경우, 시각적 맵도 함께 생성하거나 유지보수합니다.
- 증분 업데이트: 안정적인 ID를 유지하고, 변경된 사실, 연관 관계, 상태 및 맵만 업데이트합니다. 삭제된 노드에 대한 참조를 확인합니다.
- 영향 분석: 주어진 변경 사항을 중심으로 입력, 소비자, 상태, 예외 분기, 제약 조건 및 검증을 추적합니다. 사용자가 분석만 요청할 경우, 변경을 구현하지 않습니다.
프로젝트의 기존 파일과 ID를 우선 사용합니다. 새 프로젝트는 기본적으로 docs/LOGIC_MAP.md를 출력하고, 시각적 버전은 기본적으로 docs/logic-map.html을 출력합니다. 기존 이름이나 사용자가 지정한 위치가 있다면 그 우선합니다.
먼저 증거 확보, 그다음 관계 구축
프로젝트 규칙, 요구사항 기준, 주요 진입점, 페이지/워크스페이스, 상태와 저장소, 비즈니스 프로세스, 테스트 및 릴리스 기록을 읽습니다. 핵심 사용자 작업을 따라 필요한 코드를 읽으며, 저장소의 모든 파일을 일일이 탐색할 필요는 없습니다.
다음 사항을 명확히 구분해야 합니다: 요구사항 약속, 실제 구현, 자동화된 검사 증거, 실행 환경 검증, 외부 감사. 오래된 기록에는 날짜와 증거 범위를 표시합니다. 수행되지 않은 검사는 통과한 것으로 작성할 수 없습니다.
다음 사항을 중점적으로 추적합니다:
- 여러 진입점이 실제로 동일한 처리 체인을 공유하는지, 특정 단계를 우회하는 것이 있는지.
- 데이터를 누가 생성, 보유, 소비, 덮어쓰기, 해제하는지, 영속화되거나 로컬을 벗어나는지.
- 취소, 빈 데이터, 거부, 한도 초과, 구문 분석 실패가 각각 어떻게 종료되는지.
- 고빈도 업데이트, 배치, 임계값 등이 프로젝트 특정 불변 조건을 담당하는지.
문서와 코드가 충돌하는 경우 각각 기록하고, 시각적 일관성을 위해 강제로 병합하지 않습니다. 코드 리스크를 발견하면 격차로 기록하고, 작업 범위를 자동으로 수리로 확장하지 않습니다.
추적 가능한 모델 구축
references/model.md를 읽고, 그 안의 노드, 관계 및 증거 필드를 사용합니다. 프로젝트의 기존 ID를 결합하여 단순화하거나 조정합니다.
먼저 핵심 작업의 한 줄 정의와 주요 체인을 작성한 다음, 정상/예외 분기, 페이지 간 상태, 인터페이스, 제약 조건 및 검증을 추가합니다. 맵 상에서 인접하다고 해서 관계가 있는 것은 아닙니다. 모든 가장자리는 그 의미와 근거를 설명할 수 있어야 합니다.
기본 전달 구조:
- 기능 개요: 독자가 먼저 제품이 무엇을 할 수 있는지 알 수 있도록 합니다. 실제 사용자 작업별로 그룹화하며, 기술적 하위 맵의 수를 기능 수로 간주하지 않고 이 예제의 다섯 그룹에 고정하지 않습니다.
- 개별 기능 흐름: 진입점, 동작, 처리, 상태 및 종료 지점을 펼쳐 보이고 분기 조건을 표시합니다.
- 노드 설명 및 증거: 책임, 직접 연관, 구현 위치, 제약 조건, 검증 및 상태.
- 변경 영향 인덱스: 일반적인 변경 사항이 어떤 노드, 파일 및 검사에 해당하는지.
개요에서는 부차적인 관계를 생략할 수 있지만, 전체 모델이나 노드 설명에서 다시 찾을 수 있어야 합니다. 요구사항 문서는 요구사항 판정을 계속 책임지며, 맵이 별도의 요구사항 기준을 만들지 않습니다.
HTML 시각적 전달
HTML이 필요한 경우 references/visual.md를 읽습니다. 구체적인 참조가 필요한 경우 references/wechat-example.html을 확인합니다. 이는 구현된 프로젝트의 예시일 뿐, 보편적인 사실이나 고정된 레이아웃 템플릿이 아닙니다.
노드와 의미적 가장자리가 동일한 데이터를 공유하도록 합니다. 뷰 좌표, 라우팅, 테마는 별도로 관리하며, Markdown과 HTML은 동일한 ID를 사용합니다. 간단한 프로젝트는 생성기나 그래픽 라이브러리를 강제로 도입하지 않고 작은 데이터 구조를 직접 유지할 수 있습니다.
사용자가 이미 확인한 시각적 방향을 유지합니다. 기본적으로 중앙 제한 너비, 기능 개요 진입점, 개별 기능 흐름 탐색, 그림 아래 설명, 밝은/어두운 두 가지 테마를 사용합니다. 노드 수와 분할 방식은 콘텐츠 밀도에 따라 결정됩니다.
예제의 WeChat 전용 용어, 크기 임계값, 검증되지 않은 상태 또는 수동 좌표를 다른 프로젝트에 복사하지 않습니다. 제품 루트 그룹이 단지 구조를 보여주기 위한 것이라면 명확히 표시하고, 이를 새로운 비즈니스 기능으로 취급하지 않습니다.
검증 및 전달
콘텐츠 및 구조:
- ID는 고유합니다. 가장자리의 끝점이 존재합니다. 주요 기능에 모두 드릴다운 진입점이 있습니다. 삭제된 노드에 대한 미해결 참조가 없습니다.
- 포함, 데이터 흐름, 의존성, 제약 조건 및 검증은 각각 고유한 의미를 가지며, 실행 순서로 혼동되지 않습니다.
- 저장 수명 주기, 예외 종료 지점, 구현 위치 및 상태는 증거로 뒷받침될 수 있습니다.
- 한 번 구체적인 변경 사항을 자문합니다. 예를 들어 "레이아웃을 변경하면 무엇에 영향을 미치는가"와 같은 질문에 대해 맵이 관련 상태, 소비자 및 검증을 추적할 수 있어야 합니다.
시각적 버전은 실제로 브라우저를 열어 확인해야 합니다:
- 개요가 모든 주요 기능을 동시에 표시하고, 텍스트가 명확하며, 화살표가 노드나 텍스트를 가로지르지 않습니다.
- 기능 흐름을 하나씩 열어 드릴다운, 맵 간 연결, 선택 상태 및 선택 해제를 확인합니다.
- 밝은 테마와 어두운 테마의 텍스트, 노드, 연결선, 화살표 및 설명을 확인합니다. 스크린샷을 캡처합니다.
- 대상 데스크톱 크기에서 개요의 완전성을 확인합니다. 좁은 창에서는 가독성 있는 글꼴 크기를 유지하고, 맵 내 스크롤을 허용하거나 분할 맵으로 변경합니다.
정적 구문 또는 구조 검사는 시각적 검사를 대체할 수 없습니다. 브라우저를 사용할 수 없는 경우 파일을 전달하고 완료되지 않은 검사를 명확히 표시하며, 이전 스크린샷으로 현재 결과를 가장하지 않습니다.
전달 링크, 주요 관계 변경 사항, 실제 검사 결과 및 남은 격차를 제공합니다. 프로젝트의 Git 규칙에 따라 작업을 저장합니다. 자체적으로 웹사이트를 게시하거나 전역 Skill을 설치하지 않습니다.