chrislacey89/compound

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

최근 해결한 문제나 배포한 기능을 문서화하여 프로젝트 지식을 복합적으로 축적합니다. 각 문서화된 해결책은 향후 계획 및 구현을 더 빠르게 만듭니다. 에이전트는 /research 및 /write-a-prd 시 docs/solutions/를 참조하므로, 오늘 배운 교훈이 내일의 실수를 방지합니다.

작업 중 계획이나 추정에 예상치 못한 일이 있었다면 그것도 캡처하세요. 실제 작업 데이터가 미래 작업에 피드백되지 않으면 McConnell 스타일의 보정은 불가능합니다.

호출 위치

이 스킬은 복합 루프를 완성하는 주요 파이프라인 스킬입니다. 기본 전달 경로의 마지막 부근에서 실행되며, /pre-merge가 PR을 생성한 후에 실행됩니다.

기본값 — PR에 교훈을 캡처하고 병합 전. PR 시점에 재사용 가능한 교훈이 이미 알려져 있다면, 열려 있는 PR 브랜치에서 /compound를 실행하여 docs/solutions/ 항목이 해당 교훈을 가르쳐준 코드와 동일한 PR에 포함되도록 합니다. 이렇게 하면 동일한 병합 전에 리뷰되고 원자적으로 병합됩니다. 이렇게 하면 /compound가 /pre-merge와 /closeout 사이에 위치하게 되며, /pre-merge로 한 번 반환됩니다.

… → /pre-merge → /compound (PR 내부, 교훈이 있는 경우) → /pre-merge (재실행: 복합 커밋이 포스트 스탬프 델타, 재스탬프) → /closeout (병합 + 정리) → 정리

반환 단계는 장식이 아닙니다. 브랜치에 커밋하면 /pre-merge Phase 4가 작성한 스탬프를 지나 헤드가 이동합니다. /pre-merge는 스탬프의 유일한 작성자이므로, 재실행 없이 항목이 코드와 함께 병합되지만 아무도 읽지 않게 됩니다. 이것이 바로 PR 내부 기본값이 선택된 이유입니다. Phase 5는 인계를 명시하며, 이것이 그 이유입니다.

폴백 — 병합 후 캡처. 일부 교훈은 병합 중이나 후에만 표면화됩니다: 통합 문제, QA 발견, 출시 후 동작 관찰 등. 이러한 경우 /closeout이 병합된 후 /compound를 실행하세요. 이것이 폴백 경로이며 기본값이 아닙니다.

어느 경우든 /compound는 병합이나 작업트리 정리를 직접 수행하지 않습니다. 그것은 /closeout의 역할이며, 리뷰 통화 스탬프를 작성하지 않습니다. 그것은 /pre-merge의 고유 역할입니다. PR 내부 캡처는 열려 있는 PR 브랜치에 커밋하고 이를 다루는 리뷰를 위해 반환하는 것을 의미합니다. 병합을 의미하지는 않습니다.

사소한 편집이나 테스트, 린터 규칙, 코드 주석과 같은 더 높은 충실도의 아티팩트에 완전히 속하는 교훈에는 사용하지 마십시오. PR 내부든 병합 후든 아래 '사용하지 말아야 할 경우' 보호 조항이 여전히 적용됩니다. 대부분의 PR에는 재사용 가능한 교훈이 없으며, 고정된 PR당 docs/solutions/ 슬롯이 존재하지 않습니다.

존재 이유

이 단계가 없으면 AI 지원을 받은 전통적인 엔지니어링만 수행한 것입니다. 워크플로우의 처음 세 단계(계획, 작업, 리뷰)는 기능을 생성합니다. 네 번째 단계는 매번 더 나은 기능을 구축하는 시스템을 생성합니다.

사용 시기

• 기능의 PR이 준비되었고 재사용 가능한 교훈을 제공한 경우 — 병합 전에 PR에 캡처(행복 경로)
• 출시 후에만 교훈이 명확해진 경우(병합 후 폴백)
• 까다로운 버그를 수정한 후, 근본 원인이 명확하지 않았던 경우
• QA 사이클에서 더 일찍 발견할 수 있었던 문제가 드러난 후
• 상당한 트레이드오프가 있는 아키텍처 결정을 내린 후
• 재사용해야 할 패턴을 발견한 경우

사용하지 말아야 할 경우

• 사소한 수정(오타 수정, 간단한 설정 변경)
• 공식 라이브러리 문서에 이미 잘 문서화된 경우
• 교훈이 프로젝트별로 중요하지만 해당 코드를 곧 폐기할 예정인 경우
• 사전에 계획된 작업을 깔끔하게 실행한 경우(예상치 못한 일, 재작업, 명확하지 않은 결정 없음). 이슈 본문과 PR 설명이 이미 해당 기록을 담고 있으며, 재사용 가능한 교훈이 없는 docs/solutions/ 항목은 미래 독자들을 스킵하도록 훈련시킵니다.
• 의심스러운 경우 — 건너뛰는 데 비용이 들지 않습니다. 이슈와 PR은 GitHub에 남아 있습니다. 가치가 낮은 교훈을 캡처하면 미래 계획자들이 docs/solutions/를 참조할 때마다 주의를 소모합니다.

실행 흐름

Phase 1: 캡처할 대상 식별

PR 내부 기본 경로에서 리뷰 중인 작업은 열려 있는 PR 브랜치이므로 아래 명령어가 직접 읽습니다. git log와 git diff는 브랜치가 병합될 베이스와 비교하여 실행되며, 아직 병합되지 않은 상태입니다. 병합 후 폴백 경로에서는 병합된 기능의 히스토리를 볼 수 있는 세션에서 실행하세요. /closeout이 브랜치를 정리하고 베이스를 가져오면 해당 diff는 비어 있으므로 gh pr diff <n>을 대신 사용하세요. 어느 경우든 최근 작업을 검토하십시오.

먼저 베이스를 확인하세요. main을 하드코딩하지 마십시오. 이 리포지토리 자체는 prod를 사용하며, 이름은 ref가 아닙니다. 워크트리 워크플로우에서는 누구도 베이스 브랜치를 체크아웃하지 않으므로 로컬 브랜치는 체크아웃 시점에 고정되고 origin/<base>는 계속 이동합니다. sidecar.sh base-ref를 호출하세요. 베이스를 추론하지 마십시오.

SC="<이 스킬의 디렉토리>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref 실패: 베이스를 추측하지 않음" >&2; exit 1; }
git log --oneline "$BASE_REF..HEAD"
git diff --stat "$BASE_REF...HEAD"

다음 항목을 살펴보세요:

1. Git 로그 — 어떤 커밋이 생성되었는가? 무엇이 변경되었는가? 베이스 기준으로, -20이 아님: 고정된 개수는 해당 브랜치보다 짧은 브랜치에서 베이스의 자체 히스토리를 "리뷰 중인 작업"으로 읽습니다. 여기서 두 점은 정확합니다. 이는 이 브랜치에 있고 베이스에는 없는 커밋입니다. (git diff는 세 점인 이유는 병합 베이스에서 diff하여 베이스 측 작업을 빼지 않기 때문입니다.) 병합 후 폴백 경로에서 브랜치가 사라졌으므로 위와 같이 gh pr diff <n>을 사용하세요.

2. 이슈 스레드 — 원래 문제는 무엇이었는가? 어떤 논의가 있었는가?

3. diff — 어떤 파일이 변경되었는가? 어떤 패턴이 나타났는가?

사용자에게 물어보세요: "이 기능에서 가장 중요하게 배운 점이나 가장 까다로운 부분은 무엇이었나요?" 그들의 답변이 종종 가장 가치 있는 교훈을 드러냅니다.

작성하기 전에 교훈을 적절한 수준으로 분류하세요:

• 사건(Event) — 일회성 사건 또는 가시적인 실패
• 패턴(Pattern) — 기능, 버그, 또는 인계에서 반복적으로 발생한 것
• 구조(Structure) — 코드베이스, 워크플로우, 인센티브, 또는 의사 결정 프로세스에서 패턴을 계속 생성하는 반복 조건

증거로 뒷받침할 수 있는 가장 높은 수준을 캡처하는 것을 선호하세요. 교훈이 구조적이라면, 결과를 가능하게 만든 피드백 루프, 누락된 피드백, 또는 지연된 효과의 이름을 지정하세요.

계속 진행하기 전에 네 가지 질문에 답하세요:

1. 이것이 진정으로 새로운 것인가? 공식 라이브러리 문서와 Phase 4의 중복 검색이 다루는 저장소를 확인하세요. 교훈이 이미 다른 곳에 잘 문서화되어 있다면 건너뛰거나 기존 출처에 링크하세요.
2. 3개월 후에도 여전히 정확할 것인가? 교훈이 의존성 버전이나 임시 해결책에 밀접하게 연결되어 있다면, 이를 기록하세요. 이는 아래 volatility 분류에 영향을 미칩니다.
3. 이 교훈을 더 가까운 소스에 캡처할 수 있는가? 동작 불변성은 테스트에 더 적합합니다. 규칙은 린터 규칙에 더 적합합니다. "이유" 설명은 결정과 함께 있는 코드 주석에 더 적합합니다. 현재의 이유, 즉 독자가 현재 코드를 이해하는 데 필요한 이유에 국한됩니다. 이를 발견한 사건은 커밋 메시지와 PR 본문에 속하며, 히스토리를 재구성하는 독자가 이미 찾는 곳입니다. /execute Step 3은 주석이 작성되는 순간에 그 라우팅을 명시하며, 이 질문은 그에 대한 사후 확인입니다. 교훈을 더 높은 충실도의 아티팩트에 캡처할 수 있다면, 산문을 작성하는 대신 그렇게 하세요. 이는 교훈을 전달하는 것에 관한 것입니다. Phase 4의 클러스터링 확인은 메커니즘이 다음 인스턴스를 포착해야 하는지에 대한 다른 질문을 하며, 교훈 자체에 산문이 필요했더라도 재발 시에는 하나가 필요할 수 있습니다.
4. 프로세스가 수정되었는가? (버그 수정 복합만 해당.) 수정이 교정(결함 제거)인가, 아니면 해결책(실패 억제)인가? 코드베이스의 다른 곳에서 구조적으로 유사한 패턴이 발견되고 해결되었는가? 이 결함 클래스가 다시 코드베이스에 들어오는 것을 방지할 프로세스 변경은 무엇인가? 더 강력한 테스트, 린터 규칙, 어설션, 계획 체크리스트 항목, 또는 chrislacey89/skills에 제출된 이슈(아래 팩에 대한 제출 참조)인가? 답변이 "없음"이라면, 이 결함을 생성한 메커니즘이 여전히 활성 상태입니다.

팩(Pack)에 대한 제출 — 다섯 번째 메커니즘

이 하위 섹션은 버그 수정에 국한되지 않습니다. 위 Q4는 (제목에서 명시하듯이) 그렇지만, Q4와 Phase 4의 메커니즘으로 승격 규칙 모두 아래 규칙을 인용하며, Phase 4는 버그 수정에 국한되지 않습니다. 이 메커니즘이 존재하는 사건은 기능 복합이었습니다. 자체 사건이 발생하지 않은 경로에서만 접근 가능한 절차는 수정 중인 결함 자체이므로, 규칙은 여기서 한 번 선언되고 두 단계 모두 이를 참조합니다.

다섯 번째 이름은 소유권에 의해 범위가 지정되며, 난이도에 의한 것이 아닙니다. 처음 네 가지는 이 코드베이스의 아티팩트입니다. 다섯 번째는 일부 예방 변경 사항이 그렇지 않기 때문에 존재합니다. 이는 chrislacey89/skills의 스킬 산문, 게이트, 인계, 또는 계약 테스트에 대한 변경 사항으로, 어떤 다운스트림 아티팩트도 전혀 전달할 수 없습니다. 그것이 유일하게 다섯 번째 이름이 자격을 얻는 경우입니다. 처음 네 가지가 어렵거나, 비싸거나, 불분명하기 때문에 자격을 얻지 않습니다. 그것은 chrislacey89/skills#257이 의도적으로 닫힌 준수 탈출구이며, "하나를 구축할 수 없었다"는 여전히 항목에 네 가지 중 어느 것이 가장 가까웠고 무엇이 차단했는지 이름을 지정하여 해결됩니다.

제출-소유자 게이트 (DO-CONFIRM — 출력물을 작성하기 전에 확인)

제출은 현재 위치한 리포지토리에서 공개 리포지토리로 단어를 이동시킵니다. 이는 목록의 다른 모든 메커니즘(테스트, 린터 규칙, 어설션, 체크리스트 항목은 모두 제자리에 유지됨)과 다른 행위입니다. 따라서 본문을 작성하기 전에 현재 리포지토리의 소유자가 제출이 허용된 소유자인지 확인하세요.

git remote get-url origin | sed -E 's#(git@[^:]+:|https://[^/]+/)([^/]+)/.*#\2#'

아래 허용 목록과 비교하세요. 허용 목록이 전체 게이트입니다. 목록에 없는 소유자는 허용되지 않습니다. 인식하지 못하는 소유자도 포함됩니다. 이를 "내가 아는 작업 소유자 차단"으로 반전시키지 마십시오. 지난 주에 온보딩된 클라이언트 조직은 아직 아무도 목록에 없으므로, 거부 목록은 가장 덜 알려진 기밀 상태를 가진 리포지토리를 정확히 허용합니다. 알 수 없는 소유자에 대해서는 실패 시 닫으세요(fail closed).

chrislacey89

해당 펜스 주변의 마커는 하중을 지지합니다. 이 하위 섹션에는 여러 개의 펜스 블록이 포함되어 있으므로, "목록은 아래 코드 블록입니다"라는 것은 기계적으로 읽는 사람에게 모호합니다. 잘못 추측한 독자는 산문을 추출하고 모든 소유자가 검사에 실패합니다. 위치가 아니라 마커를 일치시키세요.

해당 목록에 소유자를 추가하는 것은 의도적이고 리뷰된 편집(한 줄, 오프라인, grep 가능)으로만 이루어져야 합니다. 기여하는 공개 리포지토리는 이름을 지정하면 자격을 얻습니다. 단순히 공개라고 해서 자격을 얻지는 않습니다. 가시성은 변경 가능한 원격 속성이며, 공개 포크는 비공개 부모를 앞에 둘 수 있습니다. 그리고 여기서 중요한 이유는 제출되는 것은 리포지토리의 코드가 아니라 작업에 대한 내러티브이기 때문입니다. 공개 소스와 그에 관한 기밀 참여는 일반적인 조합이며, "X를 구축하는 동안 Y에 대해 이것을 발견했습니다"는 모든 라인이 읽을 수 있을 때에도 관계를 누출합니다.

소유자가 허용 목록에 없으면 다섯 번째 이름을 사용할 수 없습니다. 이 메커니즘 이전의 동작으로 돌아가십시오: 항목의 예방 → 프로세스 수준 슬롯에 처방을 기록하고, /improve-pipeline을 권장하며, 인간이 이를 전달하도록 합니다. 교훈은 손실되지 않습니다. 단지 자동으로 이동하지 않을 뿐입니다.

작성 및 제출

소유권 가드와 제출-소유자 게이트가 모두 통과하면, 제출이 메커니즘이며 /compound가 제출합니다. 이 리포지토리에 도달하는 처방은 누군가가 그곳으로 가져가도록 권장하는 문장이 아니라 아티팩트입니다. 먼저 중복을 확인하고 새 이슈를 제출하는 대신 기존 이슈에 댓글을 답니다. 새로운 아웃바운드 채널이 백로그에 들어가는 것은 중복된 진술로 채워지지 않는 경우에만 가치가 있습니다.

gh issue list -R chrislacey89/skills --state all --search "<파이프라인 영역> <실패 모드 키워드>"
gh issue create -R chrislacey89/skills --title "[improve-pipeline] <파이프라인 영역> — <처방>" --body-file <파일>

--title과 --body*는 필수이며 스타일상 선택이 아닙니다. gh issue create에 이 둘 중 하나라도 없으면 모든 비대화형 실행자에서 오류가 발생하며, 이 메커니즘이 유지되도록 설계된 모든 AFK 경로에 해당합니다.

본문을 익명화하여 작성하고, 이를 예의가 아닌 계약의 일부로 간주하세요. 위의 게이트는 제출할 수 있는지를 결정합니다. 이것은 무엇이 넘어가는지를 결정합니다. 사건의 주제가 아닌 형태를 설명하세요:

• 변경 대상인 팩 파일, 이를 놓친 파이프라인 단계, 그리고 대신 무엇을 했어야 하는지 이름을 지정하세요.
• 다운스트림 리포지토리, 그 소유자, 클라이언트, 경로, 식별자, 이슈 및 PR 번호는 이름을 지정하지 마세요. chrislacey89/skills#266이 한 것처럼 *"다운스트림 TypeScript 웹/페이지 분석 리포지토리"*로 특성화하세요. 해당 예제는 Triggering repo: anonymized를 열고 소스가 의도적으로 식별자에서 제거되었음을 기록합니다.
• 이 항목의 경로를 증거로 인용하지 마세요. docs/solutions/… 경로는 독자가 접근 권한이 없을 수 있는 리포지토리의 파일 이름이므로 그들에게 아무것도 증명하지 못하고 다른 모든 사람에게 작업을 식별합니다. 대신 추론을 전달하세요. 항목은 집에 남습니다.

팩 파일과 실패 형태는 제안을 실행 가능하게 만드는 것입니다. 익명화 규칙이 제거하는 모든 것은 원래 리포지토리에서만 읽을 수 있었던 세부 사항입니다.

짧게 유지하세요. 이는 제안 스텁이지 작업된 제안이 아닙니다. /improve-pipeline이 이를 개발하며, 이 단계의 후반에 있는 /improve-pipeline 권장은 여전히 유효합니다. 권장하고 호출하지 마세요. 항목에 이슈 번호를 인용하세요. 인용되지 않은 제출은 다시 산문이 됩니다. 항목이 #N을 명명하거나 다섯 번째 이름이 사용되지 않았습니다.

토끼굴 검토.