// back-office

AI 자동 분개

수집한 거래를 분개까지 이어가고 싶을 때. AI 에이전트가 수집부터 분개 후보 제안까지 맡습니다.

// 상황

이런 상황이라면

분개가 병목

거래는 쌓이는데 계정과목을 붙이는 분개에서 막힙니다.

규칙이 사람 머릿속에

어떤 거래를 어디로 분개할지 담당자 경험에 의존합니다.

수집과 분개가 끊겨 있다

받아 온 데이터를 다시 정리해 분개 도구에 넣습니다.

// 흐름

어떻게 동작하나

  1. 01

    거래 수집

    은행 입출금과 카드 승인내역을 받습니다.

  2. 02

    AI 에이전트 연결

    수집 결과를 AI 에이전트에 넘깁니다.

  3. 03

    분개 후보 제안

    거래마다 계정과목 후보를 제안받아 확정만 합니다.

// schemas

사용 데이터 형식

이 시나리오에서 받는 데이터입니다. 기관이 달라도 같은 모양으로 옵니다. 필드 전체 명세는 각 데이터 형식 문서에서 확인할 수 있습니다.

// 결과물

손에 남는 것

  • 수집부터 분개 후보까지 한 흐름
  • 반복 거래의 분개 자동 제안
  • 담당자는 확정과 예외만 처리
  • 거래 적요 기반 분류

// 실행 가이드

그대로 따라 하면 됩니다

사전 점검부터 검증까지 이 페이지에서 끝납니다. 실행 방식이 여럿이면 하나만 고르면 됩니다.

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일
전체 가이드 페이지로 보기

// 더 보기

관련 시나리오

// faq

자주 묻는 질문

분개를 자동으로 확정하나요?

AI 에이전트가 후보를 제안하고, 확정은 사람이 합니다. 규칙은 점차 다듬을 수 있습니다.

어떤 거래를 다루나요?

은행 입출금내역과 법인카드 승인내역을 함께 다룹니다.

기존 회계 도구와 연결되나요?

제안 결과를 내부 도구로 보내도록 연결할 수 있습니다.

// related

함께 보면 좋은 흐름

같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.

headless

첫 수집은 작게 시작합니다

가입하고 API 키를 만드세요. 짧은 기간의 데이터로 응답 형식을 먼저 확인할 수 있습니다.