【첫 투고】 Claude Code의 routine으로 GitHub Trending을 매일 아침 일본어로 요약하는 시스템 구축

GitHub Trending에 올라온 리포지토리를, 매일 아침 일본어로 요약하는 사이트 'github 신문'을 만들었습니다.

요약은 Claude Code가 매일 아침 작성합니다. Claude API는 사용하지 않았습니다.

이 글에서는 Claude Code에 매일의 정형화된 작업을 할당하여, 정적 웹사이트를 계속 업데이트하는 시스템을 소개합니다.

사이트 사용법과 제작 동기는 note에 적었습니다.

github 신문은 GitHub Trending(일별/주별/월별) 리포지토리를 순위에 따라 일본어 요약과 함께 나열하는 사이트입니다.

• 목록: 각 항목당 한 문장의 요약. 새로 올라온 것, 계속 올라오는 것, 돌아온 것에 표시가 되어 있습니다.
• 상세 페이지: 할 수 있는 것, 사용법, 활용할 수 있는 상황, 유사한 것, 주의점, 별(star) 추이
• 배포: Atom 피드, Discord 알림

AI 관련 리포지토리는 매일같이 나오지만, README까지 읽고 따라갈 시간이 많지 않습니다. 이름과 한 문장 요약으로 '오늘은 이런 것이 나왔다'는 핵심을 파악하고, 관심 있는 것만 상세 설명이나 원문을 읽어보는 방식으로 사용을 상정했습니다.

가장 중요하게 생각한 것은 Claude Code에 전달하는 범위를 좁히는 것이었습니다.

Trending 페이지 읽기, 전날과의 비교, HTML 생성, 알림. 이들은 매번 같은 결과여야 하므로 스크립트로 작성했습니다.

Claude Code에게 맡긴 부분은 '이 리포지토리가 무엇을 할 수 있고, 어떻게 사용하는가'를 작성하는 것만으로 한정했습니다. README만으로는 이해할 수 없다면, 파일 구성이나 examples, 코드까지 읽어봐야 합니다. 이 부분은 스크립트로는 작성하기 어렵습니다.

범위를 좁히면 AI의 출력이 흔들려도 영향이 요약 범위 내에 머무릅니다. 사이트 생성이나 알림이 날짜별로 달라지는 일은 없습니다.

routine이란, Claude Code를 클라우드에서 주기적으로 또는 API로부터 실행하여 작동시키는 기능을 말합니다. 현재 플랜의 사용량 내에서 작동합니다.

routine의 프롬프트는 단 한 줄입니다.

docs/routine.md에 따라 오늘 분을 만들고 push 하라

절차는 리포지토리의 docs/routine.md에 적어두었습니다. 주요 내용은 다음과 같습니다.

• 자료의 위치와, 오늘의 자료인지 확인하는 방법
• 한 개씩 조사한 후 작성합니다. 전체를 모아서 읽고 요약하지 않습니다 (조사 방식이 얕아지기 때문)
• 알 수 없는 것이 있으면 examples나 코드를 추가로 읽습니다. 모르는 것은 쓰지 않고, 추측은 추측이라고 명시합니다.
• 작성해도 되는 파일은 data/repos/*.json과 그날의 기록인 errors만입니다. 코드는 수정하지 않습니다 - 잘 안 될 때는 커밋하지 않고 보고하는 것으로 끝냅니다

절차서를 리포지토리에 두면, 요약 작성 방식을 변경하고 싶을 때 커밋만 하면 되므로 변경 이력도 남습니다.

요약은 JSON으로 작성하게 하고, JSON Schema로 검사한 후에 push 시킵니다.

.venv/bin/python -m github_trending validate

형식이 깨진 요약은 여기서 멈추고 사이트에는 표시되지 않습니다.

매일 아침 작성하는 것은, 최근 10일 동안 처음 올라온 것만으로 한정했습니다. 이미 작성된 요약은 재사용하고, 90일 이상 지나서 다시 올라온 경우에만 다시 작성합니다.

당초에는 가져오기부터 자료 수집까지 routine에서 처리할 계획이었습니다.

하지만 routine 내부에서 GitHub API로 다른 리포지토리를 읽으려 하자 모두 HTTP 403 에러가 발생했습니다.

GitHub access to this repository is not enabled for this session

routine의 실행 환경에서는 GitHub 통신이 전용 프록시를 거치기 때문에, routine에 할당된 리포지토리 외에는 도달하지 않습니다. 네트워크 설정을 Full로 해도 변함이 없었습니다.

대책으로, 가져오기와 자료 수집은 GitHub Actions로 옮겼습니다. Actions라면 GITHUB_TOKEN으로 다른 리포지토리를 읽을 수 있습니다.

수집된 자료는 work 브랜치에 단 한 번의 커밋 상태로 덮어쓰고, routine이 그것을 전개하여 읽습니다. 자료가 매일 수백 KB가 되기 때문에 main에는 넣지 않았습니다.

- name: routine 을 시작하기
env:
ROUTINE_TOKEN: ${{ secrets.CLAUDE_ROUTINE_TOKEN }}
...

text는 routine에 그대로 전달된다. 절차서에는, 자료의 날짜가 오늘이 아니면 5분마다 검토하고, 30분을 기다려도 오지 않으면 아무것도 하지 않고 종료되도록 설정해 두었다.

더불어 다음과 같이 변경했다:

• schedule은 혼잡하기 쉬운 매시 정각을 피하여 5:47, 7:17, 8:47(일본 시간)의 세 번으로 했다. 오늘 분이 확보되었다면 두 번째 이후부터는 아무것도 하지 않는다 - 9:00에 감시 워크플로우를 실행하여, 취득 실패나 알림 누락이 있으면 Discord로 알려준다
• routine의 특정 시간에 의한 시작은 제외한다 (API를 통한 시작과 중복으로 작동하지 않도록)

Claude Code의 routine에 매일 정형 작업을 할당하고, 정적 사이트를 지속적으로 업데이트하는 시스템을 만들었다.

• AI에게 전달하는 것은 판단이 필요한 작업만 하고, 나머지는 스크립트로 고정한다
• routine에 대한 지시는 리포지토리의 절차서 1장으로 하고, 출력은 Schema로 검사한다
• routine가 건드릴 수 있는 것은 할당된 리포지토리뿐이므로, 외부 데이터 수집은 Actions에서 한다
• 순서는 시간 간격이 아니라, 이전 처리로부터 API를 통해 시작하여 만든다

나는 인프라 엔지니어이지만, 매일 아침 github 신문을 보면서 '오늘은 이런 것이 나왔구나'라고 파악하고 있다. AI 주변의 새로운 OSS를 추적하고 싶은 사람들에게 사용해 주면 좋겠다.