전체 활용 사례

// 정기 자동화 — 저장소로 받기

AI 자동 분개 (Claude Code Action)

주간 입출금을 받아 Claude Code Action 이 beancount/hledger 저널에 전표를 자동 추가한 PR. 적자 검증 통과분만.

GitHub ActionsClaude Code매주 월요일 09:00 KST

이런 분께 수집은 자동인데 전표 작성이 마지막 병목인 plain-text accounting 사용자.

Openledger/weekly-2026-W18

ledger: 주간 전표 2026-W18 · 24건 추가

  • ledger/journal/2026-W18.beancount
  • ledger/journal/_summary.md

01사전 점검

아래 명령을 그대로 붙여넣어 지금 내 환경이 준비됐는지 확인한다.

  • repo secret H6S_API_KEY 가 등록돼 있다

    gh secret list

    목록에 H6S_API_KEY 가 보인다

    아니면 — gh secret set H6S_API_KEY # 또는 repo Settings → Secrets

  • 워크스페이스에 대상 자격증명이 있다

    h6s credentials list

    그 기관에 매칭되는 자격증명이 1건 이상 보인다

    아니면 — h6s credentials create --interactive --cert

  • Actions 가 PR 을 만들 수 있다

    repo Settings → Actions → General → Workflow permissions

    "Read and write" + "Allow GitHub Actions to create pull requests" 체크

    아니면 — 두 옵션을 켠다 (yml 의 permissions 블록만으로도 동작하지만 repo 설정이 우선).

  • secret ANTHROPIC_API_KEY 가 등록돼 있다

    gh secret list

    목록에 ANTHROPIC_API_KEY 가 보인다

    아니면 — Anthropic 콘솔에서 키 발급 후 gh secret set ANTHROPIC_API_KEY

  • repo 에 ledger/ + LEDGER.md 가이드가 있다

    ls ledger/ LEDGER.md

    기존 저널 디렉터리와 분개 가이드가 보인다

    아니면 — ledger/journal/ 생성 + LEDGER.md 에 계정 분류·적요 규칙 작성.

02실행

아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.

yaml
# 수집 → Claude Code Action 으로 ledger 전표 자동 작성 → PR.
# plain-text accounting 워크플로우를 수집부터 전표 작성까지 자동화.
#
# 사전 준비:
#   - secrets.ANTHROPIC_API_KEY  (Claude API key)
#   - repo 의 ledger/ 디렉터리에 기존 전표 + AGENT 가이드(LEDGER.md)
name: 수집 + AI 전표 작성

on:
  schedule:
    - cron: '0 0 * * 1'   # 매주 월요일
  workflow_dispatch: {}

jobs:
  fetch-and-write-ledger:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v6

      - id: prev-week
        run: |
          echo "from=$(date -u -d '7 days ago' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
          echo "to=$(date -u -d 'yesterday' +%Y-%m-%d)" >> "$GITHUB_OUTPUT"

      - id: fetch
        uses: bolta-io/h6s-action@v0
        with:
          api-key: ${{ secrets.H6S_API_KEY }}
          schema: bank.transactions.cb.v1
          provider: CB_IBK
          from: ${{ steps.prev-week.outputs.from }}
          to: ${{ steps.prev-week.outputs.to }}
          output-path: ./incoming/bank/

      # Claude Code Action 이 LEDGER.md 의 가이드를 읽고
      # incoming/bank/ 의 CSV 를 ledger 저널 파일에 자동 추가.
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          direct-prompt: |
            ./incoming/bank/ 의 새 CSV 파일을 읽어 ledger/journal/${{ steps.prev-week.outputs.to }}.beancount 에
            전표를 추가해줘. LEDGER.md 가이드를 따라 계정 분류·적요·증빙을 작성.
            적자 검증을 통과해야 한다. 작성이 끝나면 incoming/ 디렉터리는 비워줘.

      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'ledger: 주간 전표 ${{ steps.fetch.outputs.summary }}'
          branch: ledger/weekly-${{ steps.fetch.outputs.job-id }}
          commit-message: 'feat(ledger): 주간 전표 자동 작성'
          add-paths: |
            ledger/
            incoming/

전표 품질은 LEDGER.md 가이드에 비례한다 — 계정과목·증빙 규칙을 구체적으로.

03검증

  • Actions 의 fetch → claude-code-action → create-pull-request 3 step 이 초록.
  • ledger/weekly-<job-id> 브랜치 PR 에 ledger/journal/<날짜>.beancount 전표가 추가됨.
  • PR diff 의 incoming/ 이 비워져 있다(처리 완료 신호).

04흔한 에러

워크플로우는 초록인데 PR 이 안 생긴다

Actions 의 PR 생성 권한이 막혀 있거나 변경 파일이 없다(중복 실행).

해결 repo Settings → Actions 에서 PR 생성 허용. 같은 기간 재실행이면 정상.

fetch step 에서 NO_API_KEY 로 실패

secret 이름이 yml 의 secrets.H6S_API_KEY 와 다르다.

해결 secret 을 정확히 H6S_API_KEY 로 등록.

CREDENTIAL_INSUFFICIENT_FOR_PROVIDER

그 provider 에 매칭되는 자격증명이 워크스페이스에 없다.

해결 h6s credentials create --interactive --cert (공동인증서 1개로 전 기관 공용).

cron 시간이 지나도 안 돈다

yml 이 기본 브랜치에 없거나, repo 가 60일 비활성이라 scheduled workflow 가 멈췄다.

해결 기본 브랜치에 머지하고, 가끔 수동 트리거해 활성 유지.

claude-code-action step 에서 인증 실패

ANTHROPIC_API_KEY secret 누락/오타.

해결 gh secret set ANTHROPIC_API_KEY 로 재등록.

전표는 생겼는데 적자 검증 실패

LEDGER.md 규칙이 모호하거나 새 거래 패턴 미정의.

해결 LEDGER.md 에 해당 패턴 규칙 추가 후 재실행.

05변형

같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.

월 단위로 전환

yaml
- cron: '0 0 1 * *'   # 매월 1일
다음다중 기관 병렬 수집