Jia-Ethan/pavedpath-code

PavedPath Code

PavedPath Code는 에이전트가 소프트웨어 엔지니어링 문제에 대한 솔루션을 처음부터 다시 고안하지 않도록 돕습니다. GitHub 및 오픈 소스 증거에서 입증된 구현 경로를 검색한 후, 가장 강력한 패턴을 최소한의 검증 가능한 변경으로 로컬 코드베이스에 적용합니다.

GitHub를 기본 증거 소스로 사용하되, 단순한 링크 덤프로 사용하지 마십시오. 목표는 로컬 코드 문제를 정의하고, 공개 저장소, 이슈, 풀 리퀘스트, 토론, 예제, 릴리스 노트 및 소스 코드에서 이미 검증된 경로를 찾고, 해당 증거의 강도를 평가한 후, 가장 강력한 패턴을 소규모 로컬 수정, 구현 경로 또는 검증 계획으로 변환하는 것입니다.

이것은 PavedPath의 코드 중심 에디션입니다. 향후 범용 PavedPath로 확장하지 마십시오. 버그, 런타임 오류, 빌드/테스트/배포 실패, 의존성 문제, 프레임워크 또는 API 사용법, 통합 장애, 구현 패턴, 엔지니어링 도구 선택, 오픈 소스 솔루션 적용 등 소프트웨어 엔지니어링 작업 전용입니다.

사용 시기

• 런타임, 빌드, 테스트, 배포, 패키지, SDK, API, 의존성, 프레임워크 또는 통합 오류가 발생한 경우.
• 불분명한 에지 케이스, 누락된 사용 패턴, 버전 동작, 불확실한 API 계약으로 인해 기능 구현이 차단된 경우.
• 로컬 문제가 메인테이너나 다른 오픈 소스 사용자가 이슈, PR, 예제, 코드, 릴리스 노트 또는 토론에서 해결했을 수 있는 문제와 유사한 경우.
• 사용자가 GitHub 또는 오픈 소스 프로젝트에서 구체적인 엔지니어링 문제를 이미 해결했는지 묻는 경우.
• 성숙한 구현 예제나 재사용 가능한 프로젝트가 특정 기능에 대한 불확실성을 줄여줄 수 있는 경우.
• 답변이 적합한 GitHub 저장소를 비교하고, 입증된 경로 중 하나를 로컬에 적용하는 방법을 설명해야 하는 경우.

카피 편집, 코드베이스가 이미 답을 제시하는 순수한 로컬 리팩터, 코드와 관련 없는 생활 결정, 자기 미디어 워크플로우, 학습 방법, 소비자 구매 결정, 또는 웹/GitHub 조사를 명시적으로 금지하는 요청에는 PavedPath Code를 사용하지 마십시오. 사용자가 명시적으로 범위를 지정하고 액세스를 승인하지 않는 한 비공개 저장소를 검사하지 마십시오.

기본 워크플로우

1. 먼저 로컬 코드 문제를 프레이밍하십시오. 목표, 증상, 오류 시그니처, 재현 경로, 버전, 런타임, 의존성/프레임워크 이름, 최근 변경 사항, 제약 조건 및 시도된 수정 사항을 캡처합니다. 확인 가능한 사실이 누락된 경우 질문하기 전에 로컬 파일/로그를 검사하십시오.
2. 증거 모드를 선택하십시오. 오류/회귀의 경우 이슈, PR, 릴리스 및 코드를 먼저 검색하십시오. 기능 또는 도구 요구 사항의 경우 저장소 후보를 먼저 검색하십시오. 기능 구현의 경우 저장소 후보와 이슈/PR/코드 증거를 모두 사용하십시오.
3. 서브에이전트 유용성을 평가하십시오. 본격적인 GitHub 조사 전에 조건부 서브에이전트 작업이 검색 범위, 증거 품질 또는 검토 범위를 개선할지 결정하십시오. 서브에이전트를 사용하지 않는 경우 검색 경로를 보고할 때 그 이유를 간략히 명시하십시오.
4. 대상 검색어를 생성하십시오. 정확한 오류 텍스트, 패키지/API 이름, 버전 번호, 프레임워크 + 증상, 파일 이름, 구성 키, 스택 트레이스 조각, 실패한 명령 이름 또는 기능 + 프레임워크/런타임/API 이름을 선호합니다.
5. 해당되는 경우 적합한 GitHub 프로젝트를 찾으십시오. 적합도, Star 수, 활동성, 비보관, 명확한 라이선스 및 실제 예제가 있는 저장소를 선호합니다. 높은 Star 수 집합이 너무 광범위하거나 정확한 문제를 놓치는 경우 Star 임계값을 낮추십시오.
6. 오픈 소스 증거 표면을 검색하십시오. 관련 오픈 소스 저장소 내에서 이슈, PR, 토론, 코드, 예제, 릴리스 노트 및 공식 프로젝트 문서를 사용하십시오. 프로젝트 자체가 문제를 해결할 수 있는 경우 저장소 검색이 필요합니다.
7. 먼저 문제 적합도를 기준으로 순위를 매기되, Star는 성숙도 신호로 활용하십시오. Star 수가 많은 저장소는 검사 대상으로 강력한 후보이지만, 메인테이너가 확인한 이슈, 병합된 PR, 릴리스된 수정, 공식 예제 및 정확히 일치하는 코드가 인기 있는 인접 프로젝트보다 우선합니다. 순위가 중요한 경우 research-rubric.md를 참조하십시오.
8. 가장 강력한 프로젝트와 증거를 심층 분석하십시오. extraction-playbook.md을 사용하여 프로젝트 기본 정보, 재사용 가능한 표면, 근본 원인 또는 구현 패턴, 버전 제약 조건, 위험, 적용 범위 및 검증 단계를 추출합니다.
9. 최소한의 적용으로 로컬 작업으로 변환하십시오. 입증된 워크플로우, API, 구성 형태 또는 아키텍처를 적합한 곳에 유지하십시오. 사용자의 로컬 인터페이스, 구성, 데이터/인증 모델, 배포 대상 또는 언어/런타임에 필요한 부분만 적용하십시오.
10. 성공을 주장하기 전에 검증하십시오. 로컬 문제에 적합한 테스트, 빌드, 재현 명령, 실제 요청, 로그, 브라우저 확인 또는 수동 검사를 사용하십시오.
11. 증거가 약하면 그렇게 말하십시오. 약한 일치를 확신 있는 권장 사항으로 부풀리지 마십시오. 오픈 소스 증거가 불충분할 때 권장 사항을 일차 원칙 또는 로컬 전용으로 표시하십시오.

서브에이전트 / 병렬 조사 가이드

서브에이전트는 조건부 조사 도구이며 기본 요구 사항이 아닙니다. 컨트롤러는 문제 프레이밍, 범위 제어, 증거 순위 매기기, 로컬 적용 및 최종 검증에 대한 책임을 유지합니다.

다음 중 하나라도 해당되는 경우 서브에이전트를 사용하십시오.

• 문제가 2개 이상의 독립적인 에코시스템, 프레임워크, 언어, 도구, 배포 표면 또는 GitHub 커뮤니티에 걸쳐 있습니다.
• 저장소 검색이 여러 쿼리 패밀리에 걸쳐 광범위한 후보 범위를 필요로 합니다.
• 이슈, PR, 토론, 코드, 릴리스 및 예제 증거를 프로젝트, 버전 또는 검색 표면별로 명확하게 분할할 수 있습니다.
• 최종 권장 사항이 독립적인 증거 검토, 위험 검토 또는 후보 거부 검토의 이점을 얻을 수 있습니다.

다음 중 하나라도 해당되는 경우 서브에이전트를 사용하지 마십시오.

• 작업이 하나의 명확한 패키지, 저장소, API 또는 메인테이너 표면이 있는 좁은 오류입니다.
• 외부 조사를 안전하게 범위를 지정하기 전에 로컬 저장소 컨텍스트, 로그, 구성 또는 재현 세부 정보를 이해해야 합니다.
• GitHub 속도 제한, 권한 부여 경계, 비공개 저장소, 비밀, 프로덕션 데이터 또는 민감한 로그로 인해 위임이 위험할 수 있습니다.
• 서브에이전트가 대부분 동일한 검색을 복제하거나 동일한 로컬 파일을 편집할 것입니다.

서브에이전트를 사용할 때 컨트롤러는 다음을 수행해야 합니다.

• 각 서브에이전트의 쿼리 패밀리, 저장소 범위, 증거 표면, 제약 조건, 허용된 쓰기 범위 및 예상 출력을 정의합니다.
• 직접 링크, 확인된 메타데이터, 문제 적합성 근거, 위험 노트 및 명시적인 거부 이유를 요구합니다.
• 별도의 구현 단계에 좁은 허용 쓰기 범위가 없는 한 서브에이전트를 읽기 전용으로 유지합니다.
• 순위를 매기기 전에 결과를 병합하고 중복을 제거합니다. 동일한 이슈, PR, 코드 경로 또는 저장소에 대한 반복 보고서를 독립적인 증거로 계산하지 마십시오.
• 최종 확정 전에 gh, 소스 읽기, 테스트, 로그, 실제 요청 또는 공식 문서를 사용하여 가장 강력한 주장을 직접 검증합니다.

GitHub CLI 우선

GitHub CLI(gh)를 기본 검색 및 검사 표면으로 사용하십시오. 브라우저 스크래핑이나 사용자 정의 스크립트보다 gh search repos, gh search issues, gh search prs, gh search code, gh repo view, gh issue view, gh pr view 및 gh api를 선호하십시오. 이 스킬을 위해 번들된 검색 스크립트를 추가하거나 의존하지 마십시오.

다음 짧은 명령 템플릿을 시작점으로 사용한 다음 쿼리, 저장소, 필드 및 제한을 로컬 문제에 맞게 조정하십시오.

gh search repos "<query>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<query>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<query>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<query>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<query> archived:false' -f sort=stars -f order=desc

명령이 403, 429, 비공개 저장소 권한 부여 오류 또는 명시적인 gh 미인증 메시지와 함께 실패하는 경우에만 gh auth status를 실행하십시오. GitHub가 403/429를 반환하는 경우 재시도, 범위 축소 또는 엔드포인트 전환 전에 발행된 속도 제한 또는 권한 부여 컨텍스트를 검사하십시오. 프롬프트, 파일, 로그 또는 메모리에 토큰, 쿠키, 비공개 저장소 콘텐츠 또는 자격 증명을 붙여넣거나 유지하지 마십시오.

검색 전략

• 좁게 시작하십시오: 정확한 오류 문자열, 예외 클래스, CLI 출력, 패키지 + 메서드 이름, 구성 키 또는 스택 트레이스 조각.
• 제약 조건을 추가하십시오: 패키지/프레임워크 버전, 언어, 플랫폼, 배포 대상, 번들러, 데이터베이스, 인증 공급자 또는 런타임.
• 관련이 있을 때 다음 순서로 표면을 검색하십시오: 이슈/PR/토론, 병합된 수정, 릴리스 노트/변경 로그, 예제/템플릿, 소스 코드, 그 다음 저장소 수준 후보.
• 오류 없이 구현이 차단된 경우 원하는 기능과 프레임워크/런타임/API 이름을 검색하십시오.
• 추세, 핫 리스트, 주제 검색 또는 참여 지표와 같은 공개 플랫폼 데이터가 필요한 경우 시각적 브라우저 스크래핑으로 시작하지 마십시오. 먼저 재사용 가능한 공개 엔드포인트, 오픈 소스 크롤러, 아카이브된 데이터셋 및 API 필드 증거를 찾은 다음, 최소한의 실제 요청으로 선택한 소스를 확인하고 익명 핫 리스트 데이터를 로그인된 검색/주제 데이터와 명확히 분리하십시오.
• 재사용 가능한 프로젝트 검색의 경우 Star 순으로 정렬된 저장소를 검색한 다음 로컬 문제와 일치하는 후보만 심층 분석하십시오. Star, 포크, 언어, 라이선스, 활동 및 기본 콘텐츠를 기록하십시오.
• 오래되었거나, 버전이 일치하지 않거나, 보관되었거나, 해결되지 않았거나, 투기적이거나, 사용자 추측에만 기반한 일치는 등급을 낮추십시오.
• Star/포크는 지원 성숙도 컨텍스트 및 유사한 적합도를 가진 저장소 간의 타이브레이커로만 사용하십시오. 문제 적합성, 메인테이너 확인 증거, 병합된 PR, 릴리스 노트, 공식 예제 또는 재현 가능한 코드보다 우선하지 않습니다.
• 보안, 인증, 결제, 인프라 또는 프로덕션 운영의 경우, 사실이 변경되었을 수 있으므로 오픈 소스 결과를 현재 공식 문서 또는 저장소와 교차 확인하십시오.

증거 기준

각 중요한 증거 항목에 대해 다음을 식별하십시오.

• 정확한 일치: 동일한 오류, 동작, API, 버전, 환경 또는 워크플로우;
• 증거 강도: 메인테이너 확인, 병합된 PR, 릴리스된 수정, 재현 가능한 코드 예제, 테스트 픽스처 또는 반복된 독립 보고서;
• 적용 가능성: 솔루션이 적용되기 위해 로컬에서 일치해야 하는 조건;
• 구현 가치: 적용할 가치가 있는 패치, 구성, API 사용법, 의존성 버전, 워크플로우, 테스트 또는 운영 패턴;
• 저장소가 후보인 경우 프로젝트 기본 정보: 이름, URL, Star, 포크, 언어, 라이선스, 활동, 기본 콘텐츠, 적합성 근거 및 적용 비용;
• 위험: 오래된 버전, 해결되지 않은 이슈, 안전하지 않은 해결 방법, 라이선스 문제, 보안/개인정보 영향, 배포 불일치 또는 과도하게 광범위한 변경.

출력 계약

PavedPath Code가 답변에 실질적인 영향을 미칠 때 다음을 포함하십시오.

• 로컬 문제 프로필: 목표, 증상/오류, 버전/환경 및 로컬 제약 조건;
• 검색 경로: 사용된 쿼리 또는 검색 방법, 검색된 GitHub/오픈 소스 표면 및 서브에이전트 사용 여부;
• 서브에이전트 추적(서브에이전트를 사용한 경우): 각 서브에이전트의 범위, 증거 표면, 주요 결과, 거부된 후보, 중복 제거 결과 및 컨트롤러가 직접 확인한 주장;
• 프로젝트 후보(GitHub 프로젝트 자체가 관련된 경우): 저장소 링크, Star, 포크, 언어, 라이선스, 활동, 기본 콘텐츠, 일치 근거 및 로컬에서 사용하는 방법;
• 주요 증거: 일치 근거와 함께 이슈, PR, 코드, 예제, 릴리스 또는 저장소에 대한 링크;
• 권장 솔루션: 직접 재사용할 내용, 로컬로 적용할 내용, 복사하지 말아야 할 내용 및 적합한 이유;
• 거부되거나 위험한 옵션: 적용되지 않거나 주의가 필요한 이유;
• 검증 기준: 수정을 확인하는 데 필요한 테스트, 빌드, 재현 명령, 실제 요청 또는 수동 확인;
• 증거가 약하거나 강력한 오픈 소스 솔루션을 찾을 수 없는 경우 신뢰도 레이블.

저장소 수준 솔루션이 관련된 경우 간결한 프로젝트 테이블을 포함하십시오. 순수한 이슈/PR/코드 수정의 경우 테이블은 선택 사항이지만 신뢰도나 적용 가능성에 영향을 미치는 경우 저장소 컨텍스트를 포함하십시오.

링크, Star 또는 인기 순위만으로 답변하지 마십시오. 연결된 증거 없이 "일반적인 GitHub 패턴"이라고 작성하지 마십시오. 외부 예제가 로컬 제약 조건을 재정의하도록 두지 마십시오.

웹사이트, SaaS, 랜딩 페이지, 테마 또는 프론트엔드 템플릿 후보 조사의 경우 모든 중요한 후보에 대해 저장소 URL과 라이브 미리보기/데모 URL을 모두 포함하십시오. 미리보기를 사용할 수 없거나 확인되지 않은 경우 이를 명시적으로 명시하고 후보를 등급을 낮추십시오.

마이그레이션 노트

github-solution-research의 이름이 PavedPath Code로 변경되었습니다. 이전 동작은 유지됩니다. 이는 PavedPath의 코드 중심 에디션을 위한 네이밍 및 포지셔닝 업데이트입니다. 새 설치는 pavedpath-code 스킬 이름과 대상 에이전트 런타임의 활성 스킬/명령 디렉토리를 사용해야 합니다.

안전 경계

• 코드 복사보다는 패턴을 읽고 기존 공개 인터페이스를 재사용하는 것을 선호하십시오. 코드 재사용이 필요한 경우 라이선스를 확인하고 저작권 표시/의무 위험을 표시하십시오.
• 기존 오픈 소스 솔루션의 대규모 재작성을 피하십시오. 입증된 흐름을 그대로 유지하고 사용자 문제에 필요한 로컬 적용만 수행하십시오.
• 저장소, README, 이슈, PR 또는 문서에서 대규모 축어적 발췌를 피하십시오.
• GitHub 토큰, 쿠키, 비공개 저장소 콘텐츠 또는 자격 증명을 출력, 로그, 스킬 또는 메모리에 저장하지 마십시오.
• 서브에이전트에 토큰, 쿠키, 비공개 저장소 콘텐츠, 민감한 로그, 비밀, 프로덕션 데이터 또는 자격 증명을 전달하지 마십시오.
• 네트워크 액세스가 불가능한 경우 오픈 소스 조사를 수행할 수 없다고 명시하고 권장 사항을 로컬 전용으로 표시하십시오.