// back-office
AI 자동 분개
수집한 거래를 분개까지 이어가고 싶을 때. AI 에이전트가 수집부터 분개 후보 제안까지 맡습니다.
// 상황
이런 상황이라면
분개가 병목
거래는 쌓이는데 계정과목을 붙이는 분개에서 막힙니다.
규칙이 사람 머릿속에
어떤 거래를 어디로 분개할지 담당자 경험에 의존합니다.
수집과 분개가 끊겨 있다
받아 온 데이터를 다시 정리해 분개 도구에 넣습니다.
// 흐름
어떻게 동작하나
- 01
거래 수집
은행 입출금과 카드 승인내역을 받습니다.
- 02
AI 에이전트 연결
수집 결과를 AI 에이전트에 넘깁니다.
- 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 --certActions 가 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_KEYrepo 에 ledger/ + LEDGER.md 가이드가 있다
ls ledger/ LEDGER.md기존 저널 디렉터리와 분개 가이드가 보인다
대안으로
ledger/journal/ 생성 + LEDGER.md 에 계정 분류·적요 규칙 작성.
02실행
아래 파일을 .github/workflows/ 에 저장하고 기본 브랜치에 commit. 첫 검증은 Actions 탭 → Run workflow 로 수동 트리거.
# 수집 → 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변형
같은 사례에서 자주 바꾸는 옵션. 다른 사례는 아래 이전/다음에서.
월 단위로 전환
- cron: '0 0 1 * *' # 매월 1일// 더 보기
관련 시나리오
// faq
자주 묻는 질문
분개를 자동으로 확정하나요?
AI 에이전트가 후보를 제안하고, 확정은 사람이 합니다. 규칙은 점차 다듬을 수 있습니다.
어떤 거래를 다루나요?
은행 입출금내역과 법인카드 승인내역을 함께 다룹니다.
기존 회계 도구와 연결되나요?
제안 결과를 내부 도구로 보내도록 연결할 수 있습니다.
// related
함께 보면 좋은 흐름
같은 데이터를 제품 연동, 내부 시스템, 자동화 작업 중 어디에 둘지에 따라 구현 방식이 달라집니다.
API 연동 — 플랫폼
API 연동 — 자체 ERP·어드민
CLI·AI 연동 — 재무 업무 자동화