mindxassociates/practice-books-kit

Practice Books Kit — 심리치료 실무를 위한 장부 정리 + 급여 처리

목적

개인 실무 소유자에게 완전하고 반복 가능한 자금 관리 시스템을 제공합니다. 이 시스템은 두 부분으로 구성됩니다:

• 파트 A — 월별 장부 정리. 에이전트에 해당 월의 은행 및 카드 명세서를 제공합니다. 에이전트는 고정 계정과표를 사용하여 모든 거래를 분류하고 손익(P&L) 워크북의 한 달 분량 열을 채운 다음, 보고하기 전에 월말 잔고가 일치하는지 확인합니다.
• 파트 B — Practice Books 앱. 에이전트가 소유자를 위해 구축 및 배포하는 소규모 관리자 전용 웹 앱입니다: 1099 계약자 및 W-2 직원에 대한 월별 급여(급여 실행, 급여 명세서, 연말 요약)와 파트 A의 P&L 워크북을 시각화하는 읽기 전용 재무 대시보드를 제공합니다.

두 부분은 서로를 강화합니다: 앱의 계약자 비용은 P&L과 대사될 수 있으며, 대시보드를 통해 소유자는 워크북을 열지 않아도 항상 최신 숫자를 확인할 수 있습니다.

이 키트를 에이전트에 전달하는 방법(이 키트를 받는 동료를 위해)

AI 에이전트에 이 전체 폴더를 제공한 다음:

1. 아래 설정 인터뷰에 답변하세요 — 에이전트는 다른 작업을 수행하기 전에 이 질문을 한 번만 해야 합니다.
2. references/categories.md의 계정과표를 확인하세요 — 해당 카테고리가 실무에 실제로 적용되지 않는 한 이름과 순서를 유지하세요. 에이전트는 첫 번째 채우기 전에 이를 확인해야 합니다.
3. 한 달 분량의 명세서를 제공하고 에이전트가 첫 번째 채우기를 수행하도록 하세요. 에이전트의 조정 및 판단 호출 목록을 검토하고, 한 번만 수정하면 에이전트가 해당 결정을 향후 월에 대한 상시 규칙으로 기록합니다.

설정 인터뷰(한 번 수집하고 기록한 후 매월 재사용)

에이전트는 첫 번째 채우기 또는 앱 빌드 전에 다음 사항을 반드시 수집해야 하며 추측해서는 안 됩니다:

• 실무: 법적 이름, 소유자 이름, 운영 주, 법인 유형.
• 계좌(레이블로 마지막 4자리면 충분):
  • 기본 사업 당좌 계좌( payer 수입이 입금되는 곳).
  • 급여 하위 계좌(실무에서 계약자에게 지급하는 데 사용하는 경우).
  • 세금/저축 하위 계좌(있는 경우, 이 계좌로의 이체는 내부 이체입니다).
  • 사업 신용카드.
  • 소유자의 개인/자산 계좌(이체를 받는 계좌, 소유자 인출을 인식하는 데 필요).
• 명세서: 소유자가 매월 명세서를 제공하는 방법(CSV 내보내기 선호, 은행에서 PDF만 제공하는 경우 PDF), 그리고 어떤 날짜 열이 해당 월을 기준으로 하는지(소유자가 달리 정하지 않는 한 게시 날짜가 아닌 거래 날짜).
• 지급 관례: 기본값은 전월 업무에 대해 매월 1일에 지급입니다. 실무의 실제 관례를 확인하거나 기록하세요.
• 인력 및 지급 조건(파트 B용): 모든 계약자/직원, 유형(1099 또는 W-2), 정확한 지급 조건 — 회수액의 %(percent of collections), 세션당 정액(flat per session), 시간당(hourly), 또는 급여(salary); 별도 자가 부담/슬라이딩 스케일 분할; 반복 공제(예: EHR 좌석 요금). 지급률을 절대 추측하지 마세요. 요율이 누락된 경우 설정하지 않은 상태로 두고 플래그를 지정하세요.
• 명세서 외 수입: 실무가 은행 피드에 나타나지 않는 자금을 어떻게 수령하는지 명시적으로 물어보세요. 예: Zelle/Venmo/현금/수표로 지급되는 감독료 또는 임대료. 해당 지급액은 매월 이메일/지급 알림에서 수집해야 합니다. 그렇지 않으면 P&L이 수입을 과소계상하게 됩니다.

파트 A — 월별 명세서-대-P&L 워크플로우

참조 파일: references/categories.md(계정과표 + 분류 가이드) 및 references/pl-sheet-spec.md(워크북 레이아웃, 수식 및 채우기 절차). 정확히 따르세요.

1. 해당 월의 모든 명세서를 수집하세요. 기본 당좌 계좌, 급여 하위 계좌, 모든 사업 카드, 그리고 명세서 외 수집(2단계)을 포함합니다. 명세서가 누락된 경우 이를 명시하고 제공된 명세서가 지원하는 만큼만 채우세요 — 보고서에 누락 항목을 명명하세요(예: "급여 계좌 명세서 보류로 인한 계약자 비용") 조용히 채우지 마세요.
2. 피드 외 수입을 수집하세요. 해당 월의 소유자 이메일/지급 알림(Zelle/Venmo "돈을 받았습니다" 알림 등)을 검색하고 확인된 사업 수취를 출처와 함께 원장에 추가하세요. 동일한 검색에서 발견된 개인 수취는 제외하고 나열합니다.
3. 모든 명세서의 모든 거래를 하나의 원장으로 구문 분석하세요: 날짜, 출처 계좌, 설명, 금액(크레딧은 양수, debit은 음수).
4. 내부 자금 이동을 제외하세요 — 이는 수입도 비용도 아닙니다:
   • 실무 자체 계좌 간 이체(당좌 ↔ 급여 하위 계좌 ↔ 세금 하위 계좌).
   • 소유자의 개인/자산 계좌로의 이체 — 이는 소유자 인출이며 비용이 아닙니다.
   • 신용카드 결제(자동 또는 수동) — 카드의 구매가 비용이며, 결제는 단지 계좌 간 자금 이동일 뿐입니다.
5. 나머지 모든 거래를 references/categories.md를 사용하여 분류하세요. 급여 계좌에서 이루어진 계약자 ACH 지급은 계약자 비용입니다. 거래가 어떤 규칙에도 맞지 않는 경우 보고서의 판단 호출 목록에 넣으세요 — 조용히 삭제하지 말고, 소유자의 승인 없이 새 카테고리를 만들지 마세요.
6. 카테고리별로 합산하여 해당 월의 열 값(비용은 음수)을 구합니다.
7. references/pl-sheet-spec.md에 따라 월 열을 작성하세요: 카테고리 셀만 작성한 다음 합계 수식을 작성하고, 쓰기 결과(셀 수)를 확인한 후 신뢰하세요.
8. 읽어오고 잔고를 맞추세요. 워크북에서 작성된 열을 다시 읽고 독립적으로 계산된 원장과 대조하여 확인하세요:
   • 분류된 수익 합계 = 총 명세서 크레딧에서 제외 항목(내부 이체 수취, 소유자 규칙에 따라 처리된 카드 환불)을 뺀 값.
   • 분류된 비용 합계 = 총 명세서 debits에서 제외 항목을 뺀 값.
   • 원장의 모든 거래가 정확히 한 번 처리되었습니다: 분류됨, 이유와 함께 제외됨, 또는 미분류로 나열됨. 잔고 맞추기가 실패하면 보고하기 전에 수정하세요 — 조정되지 않은 월을 보고하지 마세요.
9. 해당 월을 소유자에게 보고하세요: 수익, 비용, 순이익; 연간 누계; 내린 판단 호출(금액 포함) 및 상시 규칙으로 기록된 소유자의 결정; 미분류 항목; 누락된 명세서. 보고서는 사실에 근거하고 완전해야 합니다 — 소유자는 이를 바탕으로 감사합니다.

파트 A 하드 규칙

• 실제 금액만 사용하세요. 명세서의 실제 거래 금액을 사용하세요. 월을 "완료된 것처럼 보이게" 하기 위해 추정, 평균, 연간화 또는 숫자를 끼워 넣지 마세요. 불완전한 월은 불완전하다고 보고됩니다.
• 수동으로 입력된 셀을 절대 덮어쓰지 마세요. 소유자가 이미 셀에 값을 입력했고 그것이 귀하의 값과 다른 경우, 소유자의 값을 유지하고 보고서에서 충돌을 플래그 지정하며 공개적으로 조정하세요 — 기존 항목은 일반적으로 귀하가 가지고 있지 않은 출처에서 비롯됩니다.
• 비용은 시트에서 음수입니다. 합계 수식이 이에 의존합니다.
• 환급은 비용에서 차감하며 수입으로 기록하지 마세요. 누군가가 실무가 선지급한 특정 비용을 실무에 상환할 때(전형적인 사례: 계약자가 그룹 EHR 구독료를 상환하는 경우), 해당 월에 수취한 환급액을 해당 비용 카테고리에서 차감하세요. 수입으로 총계를 올리면 양쪽 모두 과대계상됩니다.
• 개인 거래는 제외하고 보고서에 나열하며, "안전하게" 분류하지 마세요.
• 소유자의 결정을 일관되게 적용하세요. 소유자가 분류를 한 번 수정하면, 규칙을 기록(이 실무에 대한 귀하의 메모/노트에)하고 이후 매월 다시 묻지 않고 적용하세요.

파트 B — Practice Books 앱

참조 파일: references/app-spec.md — 데이터 모델, 지급 규칙, 실행 수명 주기, 재무 판독기 계약, 차트 목록 및 배포 게이트. 해당 사양에 맞게 빌드하세요.

작업 개요:

1. 설정 인터뷰 데이터를 확인하세요 (특히 인력 + 지급 조건). 추측된 요율로는 재무 관련 항목을 빌드하지 마세요.
2. 로컬에서 먼저 빌드하세요. 서버 + 클라이언트 코드와 스프레드시트 계층을 스텁(stub)으로 대체하고 클라이언트가 보내는 정확한 인수 형태로 모든 서버 함수를 호출하는 로컬 테스트 하네스를 작성하세요. 최소한 다음을 포함하세요: 지급 기준 계산(백분율/정액/개인 분할), 실행 수명 주기 가드(실행은 승인됨을 거쳐 지급됨을 통과해야 함), 지급됨 → 지급 내역 쓰기, 1099 $600 플래그, W-2 FICA 임금 기준 상한, 회계 형식 문자열에 대한 재무 파서.
3. 게이트와 함께 배포하세요. 코드를 푸시한 다음 배포된 프로젝트 콘텐츠를 다시 읽고 버전을 생성하기 전에 테스트된 로컬 파일과 바이트 단위로 일치하는지 확인하세요 — 콘텐츠가 오래된 배포는 누군가 앱을 열기 전까지는 정상적인 배포와 구별할 수 없습니다. 기존 배포를 새 버전으로 업데이트하세요. 새 배포 URL을 생성하지 마세요(모든 새 URL은 누군가 업데이트해야 하는 링크이며, 이전 URL은 계속 이전 코드를 제공합니다). 업데이트 후, 배포 목록을 다시 확인하여 버전이 실제로 이동했는지 확인하세요(배포 목록은 업데이트 후 몇 초 지연될 수 있음).
4. 소유자 인증은 일회성 수동 단계입니다. 소유자가 프로젝트를 한 번 열고 범위(스프레드시트 + 메일 전송)를 승인합니다. 그때까지 앱 URL은 액세스 오류를 표시합니다 — 이는 예상된 현상이지 버그가 아닙니다.
5. 소유자를 위한 첫 실행 체크리스트: 잠금 해제, 데이터 워크북이 자동 생성되었는지 확인, 사람 동기화/추가, 각 사람의 지급 기준 및 요율 설정, 그런 다음 첫 번째(전월) 급여 실행을 초안 상태로 생성하고 승인하기 전에 라인을 검토하세요.

앱 경계(사전에 소유자에게 명시)

• 앱은 계산 및 기록만 수행합니다. 세금을 전자 신고하지 않으며(1099/W-2/941), 자금을 이동하거나 지불하지 않으며, 어떤 기관에도 제출하지 않습니다. 소유자는 평소처럼 은행에서 사람들에게 지불합니다. 앱은 그 사실을 기록합니다.
• W-2 원천징수 수치는 추정치입니다(편집 가능한 세율 탭의 연환산 백분율 방식) 소유자의 회계사가 확인할 수 있도록 — 신고 준비 완료로 제시하지 마세요.
• 앱 워크북에 전체 SSN/EIN 또는 은행 계좌 번호를 저장하지 마세요. "세금 양식 파일 있음" / "ACH 파일 있음" 플래그만 저장하세요. 전체 식별자는 실무의 기존 보안 시스템에 남아 있습니다.
• 앱은 관리자 전용입니다: 소유자 로그인 게이트(예: 서버 측에서 명단에 대해 확인되는 PIN)와 모든 서버 함수는 호출자의 권한을 다시 확인합니다. 제공자는 앱을 볼 수 없습니다. 제공자의 지급 보기(있는 경우)는 별도의 읽기 전용 화면입니다.
• 재무 대시보드는 읽기 전용입니다 — 앱은 P&L 워크북에 절대 쓰지 않습니다. 월별 채우기(파트 A)가 P&L에 숫자가 입력되는 유일한 방법입니다.

에이전트 운영 규칙

• 즉흥적인 대응보다 참조 파일을 따르세요. 참조와 실제 지침이 충돌하는 경우, 소유자의 현재 지침이 우선하며 변경 사항은 기록됩니다.
• 자신의 판단이 아닌 산출물에서 확인하세요: 쓰기 후 시트를 다시 읽고, 배포 후 배포된 코드를 다시 읽고, 코드 변경 후 테스트 하네스를 실행하세요.
• 단계가 실패하면 무엇이 실패했는지, 실제 상태가 무엇인지, 그리고 다음에 어떻게 될지 보고하세요. 시작했다는 이유만으로 채우기, 배포 또는 지급 실행이 완료되었다고 보고하지 마세요.