performance-engineer

performance-engineer 스킬 개요

performance-engineer 스킬이 하는 일

performance-engineer 스킬은 느린 시스템을 진단하고, 병목을 찾아내며, “이 엔드포인트가 느리다”처럼 막연한 문제 제기를 측정 가능한 개선 과제로 바꾸는 데 초점을 둔 트러블슈팅 및 최적화 워크플로입니다. 일반적인 코드 리뷰용이 아니라 성능 최적화 작업에 맞춰 설계되어 있어, 추측부터 시작하는 대신 기준선 측정 → 프로파일링 → 검증의 루프를 강제한다는 점이 핵심 가치입니다.

누가 performance-engineer를 써야 하나

이 스킬은 이미 살펴볼 시스템이 있고, 시간·메모리·처리량이 어디에서 빠져나가는지 좁혀가고 싶은 개발자, SRE, 백엔드 엔지니어, AI 에이전트 사용자에게 잘 맞습니다. 특히 재현 가능한 성능 저하, 지연 시간 목표, 의심되는 핫스팟은 있지만 완전히 빈 프롬프트에서 시작하고 싶지 않을 때 유용합니다.

실제로 해결하려는 일

대부분의 사용자는 단순히 “코드를 더 빠르게” 만들고 싶은 것이 아닙니다. 실제로는 이런 질문에 답해야 합니다:

• 실제로 나쁜 지표가 무엇인가?
• 병목은 데이터베이스, API, 프론트엔드, 네트워크, 런타임 중 어디에 있는가?
• 코드를 바꾸기 전에 무엇부터 측정해야 하는가?
• 최적화가 실제로 효과가 있었고 동작 회귀가 없었다는 것을 어떻게 증명할 수 있는가?

performance-engineer 스킬은 이런 조사 과정을 구조화할 때 가장 강력합니다.

이 스킬이 일반 프롬프트와 다른 이유

일반 프롬프트는 대개 추정성 해결책으로 바로 뛰어듭니다. 반면 이 스킬이 성능 최적화에 더 적합한 이유는 다음을 명시적으로 중심에 두기 때문입니다:

• 기준선 지표와 목표
• 최적화 전에 먼저 프로파일링
• 계층별 병목 위치 파악
• 변경 후 검증
• scripts/의 가벼운 리포트 및 프로파일링 템플릿

그래서 단순 아이디어 발상이 아니라 실제 엔지니어링 작업에 더 바로 쓸 수 있습니다.

설치 전에 확인할 점

다음 정보를 제공할 수 있다면 이 스킬은 잘 맞습니다:

• 살펴볼 코드베이스나 엔드포인트
• 재현 가능한 느린 경로
• 최소 하나 이상의 측정 가능한 성능 목표
• 프로파일링, 로그, 벤치마크 명령을 실행할 권한

반대로 정확성 문제, 아키텍처 선택, 혹은 관측된 성능 증상 없이 비용 추정만 하려는 경우에는 적합도가 떨어집니다.

performance-engineer 스킬 사용 방법

performance-engineer 설치 방법

다음 명령으로 repository collection에서 설치할 수 있습니다:

npx skills add https://github.com/zhaono1/agent-playbook --skill performance-engineer

설치 전에 스킬을 먼저 평가해보고 싶다면 다음 파일을 확인하세요:

• skills/performance-engineer/SKILL.md
• skills/performance-engineer/README.md
• skills/performance-engineer/references/checklist.md
• skills/performance-engineer/references/monitoring.md
• skills/performance-engineer/references/optimization.md
• skills/performance-engineer/scripts/profile.py
• skills/performance-engineer/scripts/perf_report.py

performance-engineer 스킬에 필요한 입력

performance-engineer 스킬은 코드만 던져줄 때보다 운영 맥락까지 함께 줄 때 가장 잘 작동합니다. 좋은 입력 예시는 다음과 같습니다:

• 느린 엔드포인트, 쿼리, 페이지, 작업, 또는 명령
• 현재 대비 목표 latency, throughput, memory, CPU
• 언어, 프레임워크, 런타임, 인프라 같은 환경 정보
• 문제 재현 방법
• 기존 profiler 출력, trace, 로그
• 의심 계층: DB, API, frontend, network, caching, compute

이 정보가 없더라도 프로세스 자체는 제안할 수 있지만, 추론해야 할 것이 많아져 결과 품질은 떨어집니다.

막연한 요청을 강한 프롬프트로 바꾸는 법

약한 요청:

Optimize this code.

더 나은 요청:

Use the performance-engineer skill on this Python API endpoint. Current p95 latency is 1.4s, target is under 500ms. Traffic spikes at 50 concurrent requests. We use PostgreSQL and Redis. Please identify what to measure first, likely bottlenecks, profiling commands to run, and the order of fixes to test.

왜 이 편이 더 좋은가:

• 어떤 지표를 볼지 정의되어 있고
• 목표치가 있으며
• 워크로드가 명시되어 있고
• 병목 가능성이 높은 계층이 좁혀져 있으며
• 무작정 수정이 아니라 조사 순서를 요청하기 때문입니다

실무에서 권장되는 workflow

좋은 performance-engineer usage 패턴은 다음과 같습니다:

1. 영향을 받는 사용자 경로나 시스템 작업을 정의한다.
2. 기준선 지표를 기록한다.
3. 느린 경로를 프로파일링하거나 점검한다.
4. 발견 내용을 병목 가능 계층과 연결한다.
5. 영향이 크고 범위가 작은 수정부터 먼저 제안한다.
6. 변경할 때마다 다시 측정한다.
7. 결과와 회귀 점검 항목을 문서화한다.

이 흐름은 스킬 자체의 단계 구조와도 맞아 있고, 최적화를 추측이 아니라 증거 위에 올려놓게 해줍니다.

먼저 읽어야 할 repository 파일

가장 빠르게 적응하려면 다음 순서로 읽는 것이 좋습니다:

1. SKILL.md — 활성화 신호와 분석 단계 파악
2. references/checklist.md — 최소한의 프로세스 규율 확인
3. references/optimization.md — 자주 쓰는 최적화 레버 확인
4. references/monitoring.md — 배포 후 무엇을 추적할지 확인
5. README.md — 예시 목표와 helper script 확인

스크립트는 자체 profiler가 아닙니다. 조사 결과를 일관된 형식으로 남기도록 돕는 템플릿입니다.

사용을 돕는 내장 스크립트

이 performance-engineer guide에 실질적인 가치를 더해주는 지원 스크립트는 두 가지입니다:

• python scripts/profile.py는 환경, 워크로드, 핫스팟 항목이 포함된 프로파일 템플릿을 생성합니다.
• python scripts/perf_report.py는 요약, 담당자, 기준선 지표, 발견 사항, 권장안, 검증 내용을 담는 markdown 리포트를 생성합니다.

예시:

python scripts/profile.py --name "checkout latency" --tool "cProfile" --command "python app.py" --duration "60s"
python scripts/perf_report.py --name "checkout API" --owner "payments-team"

이 스크립트들은 일회성 채팅 답변보다 반복 가능한 조사 기록을 남기고 싶을 때 특히 유용합니다.

이 스킬이 잘 찾아내도록 설계된 문제

원본 자료는 사용자가 다음과 같은 대표적 병목 위치를 점검하도록 유도합니다:

• N+1 쿼리, 누락된 인덱스, 과도한 결과 집합 같은 데이터베이스 문제
• API 과다 fetch 또는 비효율적인 serialization
• profiler 출력으로 드러나는 런타임 핫스팟
• payload 및 네트워크 비효율
• hot path에서의 caching 공백

즉, 단순히 “전체를 더 빠르게 하고 싶다”는 넓은 바람보다는 실제로 분리해낼 병목이 있을 때 이 스킬의 가치가 가장 큽니다.

더 나은 결과를 위한 실전 프롬프트 패턴

performance-engineer for Performance Optimization를 호출할 때는 아래 구조를 쓰는 것이 좋습니다:

Use the performance-engineer skill.

System:
- Service/page/job:
- Language/framework:
- Infra/dependencies:

Problem:
- Symptom:
- Current metric:
- Target metric:
- Reproduction steps:

Evidence:
- Logs/traces/profile snippets:
- Suspected bottleneck layer:

Task:
- Define measurement plan
- Identify likely root causes
- Recommend ordered fixes
- Specify how to validate improvement

이 패턴은 단순히 “왜 느리지?”라고 묻는 것보다 대체로 더 실행 가능한 답을 만들어냅니다.

도입 시 자주 막히는 지점

performance-engineer install에 기대기 전에, 다음 한계는 알고 있어야 합니다:

• 실제 profiler나 APM 도구를 대체하지는 않습니다
• 효과를 내려면 측정 가능한 증상이 필요합니다
• 워크로드를 재현할 수 없으면 도움 범위가 줄어듭니다
• 벤치마크 경로가 없으면 개선 효과를 검증할 수 없습니다

즉, 이 스킬은 조사 방법을 개선해주는 것이지, 신뢰할 수 있는 측정값을 스스로 마법처럼 만들어주지는 않습니다.

일반 프롬프트를 쓰는 편이 나은 경우

간단한 코드 스타일 정리, 작은 스크립트의 미세 최적화, 혹은 조사 없이 언어별 튜닝 팁만 빠르게 필요하다면 일반 프롬프트로도 충분할 수 있습니다. 증상에서 검증된 수정까지 가는 구조화된 경로가 필요하고 중요도가 높은 경우에 performance-engineer skill을 쓰는 편이 낫습니다.

performance-engineer 스킬 FAQ

초보자에게도 performance-engineer가 괜찮은가?

네, 다만 초보자라도 구체적인 느린 시나리오는 이미 있어야 합니다. 이 스킬은 기준선 측정 → 프로파일링 → 병목 식별 → 검증이라는 규율 있는 순서를 제공해 성급한 최적화를 피하게 도와줍니다. 반면 observability나 benchmarking의 기초를 처음부터 전부 가르쳐주길 기대한다면 초보자 친화성은 떨어집니다.

AI에게 코드 최적화를 요청하는 것보다 performance-engineer가 나은 점은?

핵심 차이는 프로세스 통제입니다. 일반 프롬프트는 캐싱, 인덱싱, 비동기 처리, 리팩터링 같은 제안을 곧바로 내놓는 경우가 많습니다. 반면 performance-engineer skill은 문제가 데이터베이스, API 계층, 메모리 동작, payload 크기, 런타임 핫스팟 중 어디에 있는지 먼저 가려내야 할 때 더 유용합니다.

이 스킬에 실제 툴이 포함되어 있나?

부분적으로 그렇습니다. repository에는 scripts/profile.py와 scripts/perf_report.py 같은 템플릿 생성기와, checklist·monitoring·optimization levers용 reference 문서가 포함되어 있습니다. 하지만 실제 런타임 profiler, 로그, 벤치마크, 환경별 명령은 직접 준비해야 합니다.

performance-engineer는 백엔드 서비스 전용인가?

아닙니다. README에는 API뿐 아니라 페이지 로드 유형의 성능 목표도 포함되어 있고, references에서도 payload와 네트워크 효율을 다룹니다. 다만 예시는 전반적으로 깊은 프론트엔드 렌더링 분석보다는 애플리케이션·서비스 조사 쪽에 더 치우쳐 있습니다.

언제 performance-engineer를 쓰지 말아야 하나?

다음 경우에는 건너뛰는 편이 좋습니다:

• 아직 측정 가능한 성능 문제가 없다
• 폭넓은 아키텍처 브레인스토밍만 원한다
• 문제의 본질이 속도가 아니라 신뢰성이나 정확성이다
• 워크로드를 재현하거나 어떤 지표도 수집할 수 없다

이런 상황에서는 스킬의 구조 자체가 주는 가치가 상대적으로 작습니다.

수정 후 모니터링에도 performance-engineer가 도움이 되나?

네. references/monitoring.md는 percentile, throughput, error rate, 회귀 알림을 추적하라고 유도합니다. 그래서 일회성 튜닝에 그치지 않고, 배포 검증까지 스킬의 지원 범위에 넣고 싶을 때 유용합니다.

performance-engineer 스킬 개선 방법

프롬프트를 길게 쓰기보다 기준선을 더 잘 주기

performance-engineer usage의 품질을 가장 빨리 높이는 방법은 다음 정보를 주는 것입니다:

• 현재 p50, p95, 또는 p99 latency
• throughput과 error rate
• memory 또는 CPU 증상
• 정확한 benchmark 또는 request path
• 변경 전후 비교 계획

장황한 서술형 맥락을 덧붙이는 것보다 이런 정보가 훨씬 가치 있습니다.

환경과 워크로드 형태를 함께 포함하기

성능 조언은 워크로드에 따라 달라집니다. 다음을 스킬에 알려주세요:

• 요청 동시성
• 데이터셋 크기
• cache warm/cold 상태
• CPU와 memory 제약
• local, staging, production 중 어떤 환경인지

포함된 scripts/profile.py 템플릿은 무엇을 남겨야 하는지 잘 상기시켜 줍니다: environment, workload, command, duration, hotspots.

검증 단계까지 포함해 우선순위 있는 수정안을 요청하기

강력한 후속 프롬프트 예시는 다음과 같습니다:

Use the performance-engineer skill to rank the top three likely bottlenecks by expected impact and confidence. For each, give the measurement to confirm it, the smallest fix to test, and the benchmark to verify improvement.

이렇게 하면 “일단 이것저것 다 해보라”는 식의 모호한 답을 줄이고, 반복 비용도 낮출 수 있습니다.

흔한 실패 패턴 피하기

사용자가 performance-engineer에서 약한 결과를 받는 가장 흔한 이유는 다음과 같습니다:

• 기준선 지표가 없다
• 재현 가능한 워크로드가 없다
• profiler나 trace 근거가 없다
• 병목을 분리하기 전에 수정안부터 요구한다
• 여러 시스템을 하나의 모호한 요청에 섞는다

첫 결과가 지나치게 일반적이라면, 대개 이 중 하나가 빠져 있습니다.

checklist를 품질 게이트로 활용하기

references/checklist.md는 짧지만 중요합니다. 최소 기준으로 취급하세요:

• 기준선 지표 기록 완료
• 병목 식별 완료
• 벤치마크로 수정 효과 검증 완료
• 회귀 테스트 추가 완료

이 체크리스트를 지킬 때 이 스킬은 단순 조언 도구가 아니라 실제 운영 가능한 방식으로 바뀝니다.

다음 반복이 더 좋아지도록 결과를 문서화하기

첫 번째 패스가 끝나면 scripts/perf_report.py로 리포트를 생성하고, 다음 실행 때 그 결과를 다시 입력으로 넣으세요. 그러면 performance-engineer skill이 매번 처음부터 시작하는 대신 실제 발견 사항, 담당자, 검증 메모를 바탕으로 추천을 더 정교하게 다듬을 수 있습니다.

근거 스니펫을 넣어 프롬프트 품질 높이기

“DB가 느린 것 같아요”라고만 말하지 말고, 다음처럼 간결한 근거 블록을 붙이세요:

• 쿼리 실행 시간 샘플
• profiler 상위 함수
• trace span 요약
• percentile별 엔드포인트 타이밍

불완전한 근거라도 출력 품질은 크게 좋아집니다. 스킬이 기본값에 기대는 대신 실제로 관측된 핫스팟과 추천을 연결할 수 있기 때문입니다.

진단과 구현의 경계를 이해하기

performance-engineer for Performance Optimization 워크플로는 진단, 우선순위화, 검증 계획 수립에서 가장 강합니다. 실제 스택에서 선택한 수정안을 구현하는 두 번째 패스와 함께 쓸 때 더 효과적입니다. 먼저 무엇이 중요한지 결정하는 데 이 스킬을 쓰고, 그다음 코딩 지원으로 변경을 안전하게 적용하세요.