병목 렌즈은(는) 무엇을 하나요?
병목을 찾으세요. 개선을 증명하세요.
수집은 로컬로 유지하고, 기본적으로 소스, 추적, 보고서를 업로드하지 마세요. 이식 가능한 지침과 번들 스크립트는 특정 에이전트 벤더가 필요하지 않습니다. 번들 경로는 이 SKILL.md를 기준으로 해석하세요. CLI는 Python 3.10+가 필요하며, 대상 어댑터는 Python 3.10+ 및 Node.js 22+를 지원합니다. Node는 벤치마크/CPU 모드를 지원하고, Python은 할당 프로파일링도 지원합니다.
워크로드 발견 및 합의
프로젝트 모듈을 가져오거나 설정 훅을 실행하지 않고 프로젝트 지침, 매니페스트, 잠금 파일, 진입점, 기존 성능/정확성 테스트를 읽으세요. 언어, 프레임워크, 인터프리터, 종속성, 실제 느린 작업을 식별하세요. Python 또는 Node 어댑터와 기존 프로젝트 런타임을 선택하세요. 다른 언어의 경우, 번들 어댑터가 지원한다고 가장하지 않고 수집기 경계를 설명하고 적절한 프로파일러를 제안하세요.
안정적인 데이터 세트, 시드, 동시성, 캐시 정책, 예상 출력이 있는 대표적이고 제한된 워크로드를 선택하세요. 신뢰할 수 있는 기존 벤치마크 또는 결과를 어설션하는 검토된 작은 드라이버를 선호하세요. 테스트 수집 및 애플리케이션 가져오기도 코드를 실행합니다. 실행 가능한 워크로드가 없으면 가설과 수집 계획을 제시하고, 측정값을 절대 만들어내지 마세요.
익숙하지 않은 저장소를 실행하기 전에 정확한 인터프리터, 작업 디렉터리, 명령과 인수, 호출 횟수, 타임아웃, 출력 경로, 가능한 데이터베이스/네트워크/파일 영향을 보여주세요. 대화에서 이미 다루지 않은 경우 해당 구체적인 워크로드에 대한 승인을 받으세요. 검사 또는 프로파일링 권한은 애플리케이션 코드를 수정할 권한이 아닙니다. 사용자가 이미 최적화를 승인하지 않은 경우 변경 전에 물어보세요. 변경되지 않고 이미 승인된 범위에 대해 다시 묻지 마세요. 종속성 설치, 프로세스 연결, 프로덕션 접근에는 각각 자체적인 승인이 필요합니다.
수집기는 사용자의 권한으로 코드를 실행합니다. 서브프로세스 분리와 타임아웃은 보안 샌드박스가 아닙니다. 필요한 경우 픽스처 또는 테스트 데이터베이스를 사용하세요. 워크로드 ID 또는 명령줄 인수에 자격 증명을 절대 전달하지 마세요. 인수와 경로는 로컬에 기록됩니다. 보고서는 내부 경로를 드러낼 수 있습니다. 단지 무엇을 하는지 알아내기 위해 알 수 없는 명령을 실행하지 마세요.
증거 수집
명령, 메트릭 정의, 통계적 결정, 종료 코드에 대해서는 references/measurement.md를 읽으세요. 공유 버전 2 형식은 references/measurement.schema.json에 정의되어 있습니다. 승인된 워크로드에 대해서만 번들 수집기를 실행하세요. 누락된 메트릭 경계를 추측하지 말고, 오래되었거나 임시 아티팩트를 다시 수집하세요.
- 먼저 계측되지 않은 벤치마크를 수집하세요. 모든 샘플, 환경 메타데이터, 워크로드 ID, 코드 개정을 저장하세요. 모든 샘플은 새 프로세스를 사용합니다. 한 번 폐기된 워밍업도 새 프로세스입니다. 이후 프로세스의 애플리케이션 상태를 워밍업하지 않습니다.
- 별도 호출로 CPU 프로필과 (Python의 경우) 할당 프로필을 수집하세요. 그 타이밍은 진단용이며 벤치마크 타이밍을 대체할 수 없습니다. Node CPU 모드는 V8 프로필과 이벤트 루프 진단을 유지합니다. 샘플 히트는 호출 횟수가 아니며 V8 프로필에는 수집기 시작이 포함됩니다. 기본 벤치마크 및 할당 수집은 각각 워크로드를 8회(워밍업 1회, 기록된 실행 7회) 실행합니다. CPU 프로필은 워밍업 없이 호출 한 번을 추가합니다. 승인된 계획에 이 횟수를 포함하세요.
- 편집 전에 기준선을 보존하세요. 새 출력 이름을 사용하세요. 스크립트는 아티팩트 덮어쓰기를 거부합니다. 내구성 있는 결과 디렉터리를 선택하고 각 JSON을 인접한 아티팩트 디렉터리와 함께 보관하세요. 데이터 세트 ID,
--input파일 해시, 시드, 개정, 관련--source파일, 캐시 정책을 기록하세요. 기록된 시드는 애플리케이션 코드를 시드하지 않습니다. 자동 메타데이터는 실제 캐시 상태나 지정되지 않은 입력을 설정할 수 없습니다. - 의미 있는 경우, 독립적으로 검토된 알려진 답변과 함께
--expected-stdout을 사용하세요. 워밍업을 포함한 모든 호출이 검사됩니다. 그 오라클 없이 자동화된 비교는 정확성을 평가하지 않습니다. 프로젝트 테스트를 별도로 실행하고 보고하세요. 좁은 출력 동등성은 모든 애플리케이션 불변성을 다루지 않습니다. - Python API 또는 워커에는 유한한 드라이버를 선호하세요. 번들 도구는 HTTP 부하 생성기, 라이브 프로세스 샘플러, 스레드 전체 CPU 프로파일러 또는 프로세스 트리 모니터가 아닙니다. I/O 바이트, 쿼리 수, 요청 백분위수 또는 처리량을 직접 측정하지 않습니다. 필요한 경우 사용자와 함께 추가 계측을 선택하고 그 범위/오버헤드를 기록하세요.
진단 및 제안
각 발견에 대해 아티팩트, 함수/파일/라인, 호출 수 또는 할당 크기, 관련 자체/누적 시간을 인용하세요. 관찰된 사실, 가설, 제안된 변경을 구분하세요. 누적 시간은 호출 트리에서 겹칩니다. 총 시간의 백분율로 더하지 마세요. 높은 누적 시간은 값비싼 경로를 식별하지만, 반드시 다시 작성할 함수는 아닙니다.
CPU 시간이 벽시계 시간보다 낮으면 대기를 암시할 수 있지만, 디스크, 데이터베이스 또는 네트워크 인과 관계를 증명하지는 않습니다. 반복된 함수 호출은 N+1 쿼리의 증거가 아닙니다. 쿼리 수/범위를 얻고 루프를 검사하세요. 할당 스냅샷은 스냅샷 시간의 라이브 할당을 설명하며, 모든 일시적 할당이나 누수를 설명하지 않습니다. 의심되는 누수는 반복된 워크로드와 보유 증거로 확인하세요. 알려지지 않은 것을 명시적으로 기술하세요.
측정된 기여도, 예상 이점, 구현 비용, 정확성 위험, 리소스 트레이드오프에 따라 변경 사항의 우선순위를 정하세요. 관련된 경우 캐시 무효화, 순서, 트랜잭션, 동시성, 메모리 효과를 설명하세요. 측정하기 전에 백분율 개선을 약속하지 마세요.
승인 내에서 최적화 및 검증
가장 작은 승인된 변경을 만들고 관련 없는 작업을 보존하세요. 관련 정확성 테스트를 실행하고 동일한 픽스처에서 출력/불변성을 비교하세요. 성공적인 프로세스 종료만으로는 정확성 검증이 아닙니다.
동일한 환경, 워크로드, 시드, 캐시 정책, 실행 횟수, 타임아웃으로 동일한 벤치마크와 영향을 받는 프로필을 반복하세요. rerun은 기록된 요청으로 현재 코드를 실행하고 입력 해시를 확인합니다. 이전 개정을 복원하지 않습니다. 계측되지 않은 타이밍은 계측되지 않은 타이밍과 비교하고, 메모리 메트릭은 동일하게 비교하세요. 공통 JSON은 다른 프로세스/스레드 범위나 런타임 타이밍 간격을 상호 교환 가능하게 만들지 않습니다. 종속성/인터프리터/워크로드가 변경되면, 호환성 검사를 우회하지 말고 별도의 실험으로 보고하세요.
번들 비교 명령을 사용하여 설명적인 중앙값/평균 변화, 구성된 실용적 임계값, 평균 차이에 대한 독립 표본 순열 증거(비교된 메트릭 전체에 Holm 보정)를 분리하세요. 결과를 보기 전에 임계값을 선택하세요. 기본값 5%는 보편적으로 의미 있지 않습니다. 범위 겹침은 유의성 테스트가 아닙니다. 테스트는 독립적이고 교환 가능한 표본을 가정합니다. 변동성을 검사하고 드리프트가 그 가정을 무효화할 수 있는 경우 A/B 측정을 반복하거나 인터리브하세요. 결정적이지 않은 결과는 동등성을 확립하지 않습니다.
자동화된 verified_improvement 상태는 측정된 워크로드와 일치하는 통과된 출력 오라클로 제한되며, 지원되는 실용적 기본 메트릭 개선이 필요하고, 다른 비교 메트릭의 지원되는 실용적 회귀로 차단됩니다. 출력 확인 실패는 종료 코드 3을 발생시키고 실행이 더 빠르더라도 검증을 차단합니다. --fail-on-regression은 지원되는 실용적 회귀가 종료 코드 1을 발생시키게 합니다. 결정적이지 않은 비교에 대한 종료 코드 0은 개선을 인증하지 않습니다. 평가되지 않거나 실패한 결과를 내러티브에서 홍보하지 마세요. 존재하고 승인된 경우 대표적인 이웃 워크로드를 실행하세요. 테스트된 시나리오에 대해서만 회귀 범위를 주장하세요. 합의된 질문이 답변되었을 때, 실행이 실패했을 때, 승인 경계에 도달했을 때, 또는 비교 가능한 측정을 얻을 수 없을 때 실험 확장을 중단하세요.
결과 전달
사용자의 언어를 사용하세요. 각 수집/비교는 Markdown 보고서와 JSON을 생성합니다. 원시 증거를 유지하면서 사용자 언어로 에이전트 해석을 추가하세요. 발견된 내용, 그 증거, 다음 실험으로 시작한 다음 다음을 포함하세요:
- 범위, 명령, 환경/개정, 입력, 반복 횟수, 측정 경계.
- 증거와 신뢰도를 포함한 발견 사항. 측정되지 않은 제안은 분리하세요.
- 수행되거나 제안된 변경 사항, 트레이드오프, 명령/결과를 포함한 정확성 검사.
- 각 비교 가능한 메트릭에 대한 before/after 중앙값 및 평균, 최소/최대, 샘플 수, 변경 백분율. 테스트와 실용적 결정은 평균을 사용합니다. 중앙값 변화는 설명적입니다. 단위와 프로세스/스레드/시작 경계를 포함하세요. 양수 변화는 더 높은 값을 의미하고, 음수는 더 낮은 값을 의미합니다. 0 기준선은 정의되지 않음으로 표시하세요.
- 상태: 측정된 기준선, 결정적이지 않음, 관찰된 개선/회귀, 또는 검증된 개선. 검증된 개선은 비교 가능한 반복 측정과 통과된 정확성 검사를 위해 예약하세요. 속도 향상이 메모리 증가를 동반하면 트레이드오프일 뿐, 무조건적인 승리가 아닙니다.
- 테스트되지 않은 경로, 사용할 수 없는 메트릭, 노이즈, 다음 조치, 구체적인 기록된 재실행 명령. 번들
scripts/demo.py알려진 답변 데모를 명확히 표시하고 그 숫자를 애플리케이션 결과로 재사용하지 마세요.
Markdown/JSON 파일은 이식 가능한 기준선입니다. 에이전트는 사용 가능한 프레젠테이션 도구를 사용하여 차트를 추가할 수 있습니다. 이 워크플로를 완료하기 위해 호스팅된 대시보드, 외부 AI 엔드포인트, 독점 커넥터 또는 선택적 차트 도구에 의존하지 마세요.