Sunwood-ai-labs/SourceSage

SourceSage CLI

개요

이 저장소 체크아웃에서 SourceSage CLI를 사용하여 현재 저장소 또는 다른 로컬 저장소의 저장소 요약을 생성합니다.

로컬 체크아웃을 사용하는 것이 sourcesage가 전역에 설치되어 있다고 가정하는 것보다 선호됩니다. 이 저장소 레이아웃에서 SourceSage 도구 루트는 이 SKILL.md가 포함된 디렉터리입니다.

워크플로

1. SourceSage 도구 루트와 대상 저장소를 확인합니다.

   • 사용자가 다른 저장소를 지정하지 않은 경우 현재 작업 공간을 분석합니다.
   • 현재 작업 공간이 SourceSage 저장소가 아닌 경우, 자체 체크아웃에서 uv run --directory <sourcesage-root> sage ...를 사용하여 SourceSage를 실행합니다.

2. 요청을 충족하는 가장 간단한 명령어를 선택합니다.

   • 현재 저장소 요약: uv run sage
   • 현재 저장소 요약 (라이트 모드): uv run sage --lite
   • 현재 저장소 요약 (일본어): uv run sage -l ja
   • 다른 저장소 (기본 출력 위치는 해당 저장소 내부): uv run --directory <sourcesage-root> sage --repo "<target-repo>"
   • 다른 저장소 (라이트 모드): uv run --directory <sourcesage-root> sage --repo "<target-repo>" --lite
   • 다른 저장소 (명시적 출력 디렉터리): uv run --directory <sourcesage-root> sage --repo "<target-repo>" -o "<output-dir>"
   • 비권장 diff 보고서: uv run --directory <sourcesage-root> sage --repo "<target-repo>" --diff

3. 실행 후 생성된 아티팩트를 확인합니다.

   • 저장소 요약: <output-dir>/.SourceSageAssets/Repository_summary.md
   • 비권장 diff 보고서: <output-dir>/.SourceSageAssets/RELEASE_REPORT/Report_<latest-tag>.md
   • 생성된 마크다운을 열고 명령어가 실행되었다는 사실만 보고하는 대신 중요한 결과를 요약합니다.
   • --lite 모드에서는 요약이 트리, Git 정보, 통계 및 루트 README 파일을 유지하면서 ## File Contents 섹션은 생략하는지 확인합니다.

4. 부작용 및 명령어 불일치를 보고합니다.

   • SourceSage가 <repo>/.SourceSageignore 파일을 생성할 수 있습니다 (존재하지 않는 경우).
   • --ignore-file을 지원되는 무시 재정의(override)로 취급합니다.
   • CLI가 업데이트되고 재확인되지 않는 한 --use-ignore에 의존하지 마십시오. 현재 CLI는 해당 플래그를 제공하지 않습니다.

명령어 참고 사항

• pyproject.toml이 sage와 sourcesage 진입점을 모두 정의하므로 SourceSage 저장소 내에서는 uv run sage를 선호합니다.
• SourceSage 저장소 외부에서는 uv run --directory <sourcesage-root> sage ...를 선호하여 전역 설치 없이 이 체크아웃을 사용합니다.
• 패키지가 이미 설치되어 있고 uv를 사용할 수 없는 경우에만 sourcesage 또는 sage를 직접 사용하는 것으로 대체합니다.
• 출력 언어는 -l ja 또는 -l en을 사용합니다.
• 무시 규칙이 아직 조정되지 않았거나 전체 파일 발췌가 요약을 너무 크게 만들 때는 첫 번째 탐색 패스로 --lite를 사용합니다.
• 사용자가 저장소 루트 외부에 아티팩트를 원할 경우 -o를 사용합니다.
• 이 체크아웃에서 다른 저장소를 분석하려면 --repo를 사용합니다.

검증

• 설명만 하지 말고 선택한 명령어를 실행합니다.
• 예상되는 마크다운 파일이 존재하는지 확인합니다.
• 생성된 출력을 읽고 경로와 생성된 내용에 대한 간단한 요약을 보고합니다.
• 실행 명령어나 이를 언급하는 문서를 변경한 후에는 정확히 동일한 명령어를 다시 실행합니다.

피해야 할 사항

• README 예제가 sourcesage/cli.py와 다를 때 권위 있는 것으로 가정하지 마십시오.
• 사용자가 특정 대상을 요청했고 해당 대상에 이미 결과가 있는 경우 기존 아티팩트를 조용히 덮어쓰지 마십시오.
• 이 저장소에서 pyproject.toml과 sourcesage/cli.py를 검사할 수 있을 때 기억에 의존하여 SourceSage 사용법을 설명하지 마십시오.