Communitygithub.com

truepath

의사 결정 규칙이나 버그 경로를 단계별로 설명하는 자체 포함형 HTML 시뮬레이션을 생성합니다. 하나의 점이 실제 경로를 따라 이동하고, 데이터 패널이 각 단계의 변화를 보여주며, '이전/이후' 시나리오를 나란히 표시하고 첫 번째 차이점을 표시합니다. 평결은 저장소 자체 코드(고정된 git 스냅샷에서 실행된 오라클)나 선언된 JS 포트에 의해 계산되며, 빌드는 이와 모순되는 내용을 쓰지 않습니다.

truepath란 무엇인가요?

truepath는 개발자가 프로세스 흐름, 버그 경로, 의사 결정 규칙을 대화형 HTML 시뮬레이션으로 시각화할 수 있는 스킬입니다. 'spec.json' 파일에서 노드, 엣지, 시나리오 및 평결 출처를 정의하고, 'build.py'가 평결을 계산하고 그래프를 배치하며 검사를 실행하여 하나의 오프라인 HTML 파일을 생성합니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 코딩 에이전트와 함께 사용하도록 설계되었으며, 코드 기반 평결(오라클)과 논의 중인 규칙(JS 포트) 모두를 지원합니다. 실제 코드에서 계산된 평결과 사용자 정의 시나리오를 결합하여 '프로세스 실행 보기', '버그 애니메이션', '이전/이후 비교' 등의 요청에 응답할 수 있습니다. 빌드는 13개의 검사(C1-C13)를 수행하여 시나리오가 코드와 일치하도록 보장하며, 불일치가 있을 경우 출력을 거부합니다. 그리드 레이아웃을 통해 여러 규칙을 나란히 비교할 수 있어 복잡한 의사 결정 논리를 설명하는 데 특히 유용합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bastien-gallay/truepath/tree/HEAD/skills/truepath

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

truepath은(는) 무엇을 하나요?

하나의 spec.json이 프로세스(노드, 엣지), 시나리오(경로, 메시지, 캡션, 입력) 및 평결 출처를 설명합니다. build.py는 평결을 계산하고, 그래프를 배치하며, 검사를 실행하고, 하나의 오프라인 .html 파일을 쓰거나 아무것도 쓰지 않습니다.

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (또는 아무것도 없음)
layout.py ──┘                                └► fixture.json (--export)

워크플로우

  1. 대상 주제의 노트 옆에 있는 가장 가까운 예제를 복사하고(파일 참조), spec.json의 이름을 <subject>.spec.json으로 바꿉니다.

  2. 노드와 엣지를 설명합니다. 모든 싱크 노드(결과)는 kind를 가집니다. kind는 유일한 색상이며, 각각 범례 레이블이 있습니다.

  3. 평결 출처를 선택합니다(아래 참조): 규칙이 코드에 존재하는 경우 oracle, 그렇지 않은 경우 JS port를 사용합니다.

  4. 시나리오를 작성합니다. 각 시나리오는 origin, inputs, 예상 평결 필드(expect), 그리고 실제 엣지를 따라가는 steps를 선언합니다.

  5. 빌드한 후 파일을 엽니다:

    python3 <skill-dir>/scripts/build.py <subject>.spec.json
    
  6. 위반 사항을 읽고, 스펙을 수정합니다. 검사는 절대 수정하지 마십시오.

spec.json은 sim.html을 빌드하고, <subject>.spec.json은 <subject>.sim.html을 빌드합니다. -o는 다른 파일 이름을 지정합니다.

페이지는 세부 패널이 열린 상태로 첫 번째 탭에서 열립니다. 패널을 접으면 개요로 전환됩니다: 전체 경로가 그려지고, 하나의 점이 그 위를 반복해서 이동합니다.

평결 출처

출처스펙 키사용 시기패널에 표시되는 표시
오라클oracle규칙이 저장소에 존재할 때✓ code
포트port: "decide.js"아직 코드가 없거나, 논의 중인 규칙이거나, 코드가 없는 프로세스일 때⚠ ported

오라클 프로토콜. build.py는 oracle.ref의 git archive를 가져오고(절대 라이브 체크아웃이 아닙니다. 작업 중인 브랜치는 빌드 중에 이동할 수 있습니다), oracle.paths를 추출하고, oracle.link(일반적으로 node_modules)를 링크하고, oracle.files를 그 안에 복사한 다음, oracle.cwd에서 oracle.cmd를 다음 환경 변수와 함께 실행합니다:

  • TRUEPATH_ORACLE_IN: 모든 시나리오의 inputs를 담은 JSON 배열;
  • TRUEPATH_ORACLE_OUT: 동일한 순서로 평결의 JSON 배열을 쓸 경로.

oracle.repo는 상대 경로일 경우 스펙의 폴더에서 읽습니다. link와 files는 모두 {스냅샷 경로: 출처} 형식으로 작성됩니다. link는 저장소의 경로, files는 스펙 옆의 파일입니다.

평결은 필드의 객체입니다. outcome은 필수입니다: 경로가 끝나야 하는 노드를 지정하며, 시나리오를 로직에 연결합니다. basis는 선택적으로 필드별로 실제 코드가 계산했는지("code: …"), 접착 코드가 동작을 복사했는지("port: …"), 또는 시뮬레이션이 정의했는지(다른 텍스트, ◇ definition으로 표시)를 나타냅니다. 페이지는 기준이 있는 모든 패널 값 옆에 해당 표시를 보여주고, 호버 시 전체 텍스트를 표시하며, --export는 기준이 code인 필드만 단언합니다. 기준이 없는 필드는 오라클에서는 코드로, port에서는 포팅된 것으로 간주합니다. 하나의 오라클에서 혼합될 수 있습니다: 아직 논의 중인 규칙은 코드가 이미 실행하는 규칙 옆에 포팅됩니다. 모든 실행기가 작동합니다: 프로젝트 자체 프레임워크의 테스트 파일, 스크립트, Java용 JUnit 테스트. 바닥글에는 평결을 생성한 ref와 짧은 sha가 표시됩니다.

테스트 파일 오라클은 회귀 테스트 스위트로도 사용할 수 있습니다: TRUEPATH_ORACLE_IN이 설정되면 평결을 쓰고, 그렇지 않으면 내보낸 fixture를 읽고 단언합니다. 시나리오는 스펙에 한 번만 존재하며 CI에서 실행됩니다. examples/loyalty-tier/src/oracle.js는 둘 다 수행합니다.

스펙 참조

키형태참고
title, subtitle, source문자열source는 바닥글에 표시됩니다. 스펙의 모든 텍스트와 마찬가지로 HTML로 읽히지 않고 텍스트로 표시됩니다.
langen(기본값) 또는 fr페이지 자체 단어의 언어; 스펙의 텍스트는 해당 언어로 작성됩니다.
kinds{id: {label, color}}최대 4개
nodes[{id, label, role?, kind?}]role: "decision"은 분기점을 표시합니다. 경로가 시작되는 곳은 찾아서 원형으로 그립니다. 싱크는 kind가 필요합니다.
edges[[from, to, label]]레이블이 없으면 ""
panel[{label, value, at, labels?, digits?, compared?}]value는 inputs.x 또는 verdict.y를 읽습니다. at 단계부터 표시됩니다(0은 첫 번째). labels는 값을 페이지에 표시할 내용에 매핑합니다("true", "false", "null", "[]"에 대해 해당 값). digits는 숫자 코드를 해당 길이로 제로 패딩합니다. compared: true는 한 쌍이 비교하는 항목(수정, 규칙)의 이름을 지정하는 행이며, 첫 번째 차이 검색에서 제외됩니다.
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: {kind: real|illustrative, text}; steps: [{hop: [from, to], message, caption}]; undecided: true는 아직 결정되지 않은 규칙을 표시합니다. caseName은 내보낸 fixture에서 사례의 이름을 지정합니다.
pairs[{before, after, tab, summary}]두 시나리오 ID로, −와 +로 나란히 재생됩니다. 동일한 단계 수를 가집니다.
grid{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}scenarios와 pairs 대신 사례 × 답변(또는 규칙, 수정)입니다. 아래 참조.
oracle{repo, ref, paths, link?, files?, cwd, cmd}위 참조
portdecide(inputs)를 내보내는 CommonJS 파일의 경로오라클이 없을 때 사용합니다.
export{dir, fixture, assert}--export <worktree>는 fixture를 해당 위치에 씁니다.

여러 규칙 비교: 그리드

질문이 "각 가능한 답변이 각 사례에 대해 무엇을 하는가"일 때 grid를 선언합니다. 평평한 규칙 목록보다는 질문을 선호합니다: 독자가 질문별로 결정하므로 페이지도 그렇게 배치되어야 합니다.

  • baseline: {id, label, short?, inputs}, 오늘날의 상황;
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]. cases는 해당 질문이 결정하는 사례를 나열합니다. if: {"Q1": "1A"}는 해당 답변 이후에만 질문을 표시합니다. build.py는 일관된 답변 집합(1A+2A, 1A+2B, 1B)당 하나의 변형을 도출하고 옵션의 inputs를 병합합니다.
  • cases: [{id, label, summary, origin, inputs, steps?}]; label은 독자가 아는 단어로 행의 이름을 지정하며, 사례 코드가 아닙니다.
  • steps: 모든 셀에서 공유되며, 사례가 자체 steps를 가져오지 않는 한 사용됩니다.
  • expect: {case: {variant: {field: value}}}, C3에서 검사합니다.
  • show: 행렬 셀이 표시하는 하나의 패널 행입니다(기본값은 hover의 첫 번째 행). hover: 셀이 호버 시 표시하는 행입니다.
  • summary: 행렬 위의 한 줄입니다.

baseline을 ID로 하는 평평한 variants: [{id, label, short?, note?, inputs}]도 여전히 작동합니다. 행렬은 하나의 섹션을 가지며, 모든 변형에 대해 모든 사례가 표시됩니다.

페이지는 행렬에서 열립니다: 질문당 하나의 테이블, 각 질문의 사례가 오늘날과 각 답변에 대해 표시되고, 셀의 라인이 오늘날과 다른 경우 ≠로 표시됩니다. 사례별 탭은 없습니다. 셀을 클릭하면 해당 사례가 열리고, 오늘날이 해당 답변 옆에 표시되며 첫 번째 차이점이 표시됩니다. 두 개의 버튼 행(−와 +)은 섹션의 답변 중 하나를 선택하고(1A를 1B 옆에, 오늘날 옆에만이 아니라), 각 버튼은 해당 질문의 이름으로 표시됩니다. ← matrix는 뒤로 돌아갑니다. 패널에서 "value": "answer"와 "compared": true를 가진 행은 재생 중인 답변의 이름을 지정합니다.

단계 템플릿. message, caption 및 hop은 {inputs.x} 또는 {verdict.y}를 인용할 수 있습니다. 로직 실행 후 채워지며, 동일한 경로를 읽는 패널 행과 같은 형식으로 표시됩니다. {verdict.outcome}으로의 hop을 사용하면 하나의 단계 목록이 모든 규칙에 사용될 수 있습니다.

검사

Id거부 조건
C1hop이 엣지가 아닌 단계
C2끊어지거나, 소스 노드에서 시작하지 않거나, 단계가 없는 경로
C3로직과 모순되는 expect 필드
C4로직의 outcome 이외의 곳에서 끝나는 경로, 또는 아무 것도 제공하지 않는 로직
C5kind가 없는 결과, 범례가 없는 kind, 4개를 초과하는 kind
C6상자보다 넓은 레이블(13px 고정폭)
C7실제 또는 예시임을 명시하고 출처를 밝히지 않은 시나리오
C8함께 진행할 수 없거나 알 수 없는 시나리오 쌍
C9시나리오에 없는 필드를 읽는 패널 행
C10존재하지 않는 패널 행을 참조하는 행렬 셀
C11셀이 여전히 다른 질문에 의존하는 질문 아래에 표시된 사례
C12행렬 섹션에 없는 사례, 또는 알 수 없는 사례를 참조하는 섹션
C13시나리오에 없는 단계에 나타나도록 설정된 패널 행

C3과 C4가 핵심입니다: 코드가 수행하지 않는 작업을 말하는 시나리오는 게시될 수 없습니다. C6은 스펙보다는 레이아웃을 보호합니다. 상자는 레이블 크기에 맞게 조정되므로 layout.py가 더 이상 그렇게 하지 않는 경우에만 실행됩니다. 새 검사가 작동함을 증명하려면 tests/에서 입력을 한 번 깨뜨리십시오. 각 검사는 build.py의 하나의 함수이며, 이 테이블의 ID 아래 CHECKS에 나열됩니다.

빌드가 전혀 읽을 수 없는 스펙(누락된 키, 알 수 없는 노드로의 엣지, 예외를 던지는 포트)도 검사가 실행되기 전에 일반 언어로 동일한 방식으로 거부됩니다.

디자인 규칙

  • 다이어그램당 하나의 움직이는 요소: 단일 점, 일정한 속도, 한 번에 하나의 hop. 두 개의 다이어그램이 나란히 동기화되어 이동합니다.
  • 사용된 엣지는 실선, 사용되지 않은 엣지는 점선과 회색; 경로에서 벗어난 노드는 희미해집니다.
  • 색상은 결과 종류만 인코딩합니다. 쌍에서 첫 번째 차이점(패널 값이 달라지는 첫 번째 단계)은 호박색으로 윤곽선이 표시되고 양쪽에 ≠가 표시되며 패널에 − / + 열이 표시됩니다.
  • 예시 시나리오는 실제 사례가 해당 결과에 도달하지 않는 경우에만 사용합니다. 실제 사례의 출처(티켓, 기록, 측정값, 날짜)를 명시합니다.
  • 그리드는 셀당 하나의 필드를 표시합니다. 셀당 세 개의 필드는 행렬을 읽기 어렵게 만듭니다.
  • 기본적으로 밝은 테마, prefers-color-scheme 아래에서 어두운 테마; 웹 폰트가 없으므로 파일이 오프라인에서 작동합니다.

파일

경로역할
scripts/build.py스펙을 읽고, 평결을 가져오고, 검사를 실행하고, 페이지와 내보내기를 씁니다.
scripts/runtime.html페이지; build.py는 이미 형식화된 표시할 내용만 제공하고 스펙의 다른 것은 제공하지 않습니다.
scripts/layout.py계층형 레이아웃: 상자는 레이블 크기에 맞게 조정되고, 직교 엣지를 사용합니다.
examples/refund-window/JS 포트와 이전/이후 쌍
examples/free-shipping/그리드: 두 개의 미해결 질문, 각각 변경하는 사례에 대해 결정됩니다.
examples/loyalty-tier/폴더 자체 src/에 대한 오라클, 접착 코드 및 --export가 쓰는 fixture

생성된 파일(.truepath/, 오라클 스냅샷이 있는 곳, 그리고 스펙 옆의 *.html)은 빌드 출력입니다. 포트 예제는 실행하지 않고도 스킬을 볼 수 있도록 sim.html을 유지합니다. loyalty-tier는 유지하지 않습니다. 바닥글에 평결을 생성한 커밋이 표시되므로 페이지는 커밋마다 변경되며, 이를 포함하는 git 저장소 내에서만 빌드됩니다.

제한 사항

  • 하나의 다이어그램 유형: 프로세스 흐름. 시퀀스 및 아키텍처 뷰는 구축되지 않았습니다.
  • C6는 macOS(ui-monospace)에서 측정됩니다. 더 좁은 Windows 글꼴은 여백만 추가합니다.
  • 단계는 선언되며 로직에서 파생되지 않습니다. C3과 C4는 잘못된 결과는 포착하지만 잘못된 중간 메시지는 포착하지 못합니다.

관련 스킬