📦 공개자료 · 생태계 · standarda 생태계 · L05

standarda-core: 공통 기능

작성일자 2026-07-30 · 수정일자 2026-07-30 · 예상소요 25분

목표 core 를 따로 둔 이유(단일 출처), 무엇이 들었는지, 왜 '설치'하고 자동 업데이트하지 않는지, 누가 관리하는지 이해한다.

이 강의가 이 챕터에서 가장 중요합니다. 왜 core 를 따로 뺐는지부터 시작합니다.

1. 왜 core 를 따로 뺐나: 중복 복사 vs 단일 출처

상황: 5개 프로젝트가 모두 "PDF 읽는 코드"(예: 200줄)를 필요로 합니다.

❌ 방법 A: 프로젝트마다 그 200줄을 복사·붙여넣기. 버그를 하나 발견하면 5군데를 전부 똑같이 고쳐야 하고, 하나라도 빠뜨리면 그 프로젝트만 옛 버그가 남습니다. 시간이 지나면 5개 복사본이 조금씩 달라져 제각각이 됩니다.
✅ 방법 B: 200줄을 딱 한 곳(core)에 두고 다 같이 씀. 각 프로젝트는 코드를 갖지 않고 설치해서 import 만 합니다. 버그를 고치면 core 한 곳만 고치고 버전을 올립니다. "원본이 하나"라 절대 제각각이 되지 않습니다 → SSOT(단일 출처).

❌ 방법 A: 복사본 5개              ✅ 방법 B: 원본 하나 + 설치
제품 A/    → pdf.py (200줄)         standarda-core/ → pdf.py (200줄)  ← 원본 "딱 하나"
제품 B/    → pdf.py (200줄)           │  pip install (버전 태그로)
제품 C/    → pdf.py (200줄)           ├──▶ 제품 A  (from standarda_core... import)
제품 D/    → pdf.py (200줄)           ├──▶ 제품 B
제품 E/    → pdf.py (200줄)           └──▶ 제품 C · 제품 D · 제품 E

	복사 (A)	core 로 분리 (B)
코드 위치	프로젝트마다 복사본 N개	원본 딱 1개
버그 수정	N군데 다 고쳐야	한 곳만 고치면 끝
시간 지나면	제각각으로 어긋남	항상 동일

from standarda_core... import ... 한 줄의 뜻은 "이 코드는 내 프로젝트 안에 없다. 별도 패키지(core)에 있는 걸 설치해서 불러 쓴다"입니다. 한 문장으로: "같은 걸 여러 번 만들지 말고, 한 번 만들어 다 같이 쓰자."

2. core 의 구성: 세 갈래

core 의 부품은 성격별로 세 갈래로 나뉩니다.

standarda_core/
├── clients/          ← 외부 서비스 연결 (구글과 통신)
│     gmail·sheets·drive·docs·auth
├── standard_utils/   ← 문서 → 텍스트 변환 (파일을 AI 가 읽게)
│     pdf/excel(text·vision)·document_text·sheets_text·llm_response
└── (루트)            ← LLM·워크플로우 엔진 (AI 두뇌)
      llm·llm_cache·tool_loop·verification·presentation

기억법: clients = 바깥세상(구글)과 통신, standard_utils = 파일을 AI 가 읽게 변환, 루트 = AI 두뇌·엔진.

3. core 는 '실제로 일하는 코드'

Q. core 는 사용법 설명서야, 실제 실행 코드야?

A. 실제로 일하는 코드입니다. 설명서가 아닙니다. 예: gmail_client.py 의 send_email_with_attachment() 는 "메일 보내는 법을 적은 글"이 아니라, 호출하면 진짜로 구글에 접속해 메일을 발송하는 코드입니다.

단, 혼자 켜지지 않습니다. core 는 라이브러리(부품)라 "시작 버튼"이 없습니다. 프로젝트가 불러서 호출할 때만 작동합니다. (설명서가 아니라 실제로 도는 부품이지만, 프로젝트에 연결돼 호출될 때 비로소 작동한다는 뜻입니다.)

Q. 계정 같은 디테일은 어디서 관리하고, 실행은 누가 해?

A. 디테일(누구 계정이냐)은 프로젝트가 소유하고 core 에 인자로 넘깁니다. core 는 그 정보로 실제 실행만 합니다. - 프로젝트: "이 계정으로, 이 사람한테, 이 내용 보내줘" (디테일 제공) - core: 실제로 구글에 접속해 발송 실행 (계정 모르는 범용 기계)

4. 재료 3층: Django·core·template

프로젝트가 합쳐 쓰는 재료는 사실 3층입니다. 출처와 방식이 다 다릅니다.

층	무엇	만든 주체	방식	설치 후 위치
① Django	웹 프레임워크 본체	남(오픈소스)	pip 설치(PyPI)	프로젝트 venv 안
② standarda-core	공용 기능 부품	우리 팀	pip 설치(깃허브 태그)	프로젝트 venv 안
③ template 뼈대	①②를 엮어 쓰는 내 코드	우리 팀	cookiecutter 복사	프로젝트 폴더 안(내가 고침)

집 짓기 비유:
① Django   = 공구·자재 (망치, 목재)   → 철물점에서 사 옴 (pip 설치)
② core     = 미리 만든 부품 (창틀, 문)  → 본사에서 배송 (pip 설치)
③ template = 설계도대로 지은 집 뼈대    → 설계도 복사해 시공 (cookiecutter)

Q. Django 는 standarda 폴더 중 하나야?

A. 아닙니다. Django 는 standarda- 어디에도 속하지 않는 외부 오픈소스(전 세계가 씀)입니다. 우리 깃허브가 아니라 인터넷(PyPI)에 있습니다. 재밌는 점은 core 도 Django 와 똑같은 방식(requirements.txt + pip install)으로 들어온다는 것입니다. 차이는 "누가 만들었나"(PyPI vs 우리 깃허브)뿐입니다.

💡 pip / venv - pip = 파이썬용 앱스토어(설치 도구). requirements.txt = 설치할 목록. - venv(가상환경) = 프로젝트 전용 창고. pip 으로 설치한 것(Django·core)만 여기 들어갑니다. template 코드는 안 들어가고 프로젝트 폴더에 그냥 놓입니다. 프로젝트마다 창고를 따로 둬야 서로 다른 core 버전을 품고도 안 싸웁니다.

Q. 왜 template 은 복사하고 core 는 설치해? 둘 다 공통인데?

A. 판단 기준은 딱 하나: "이 코드는 프로젝트마다 달라져야 하나, 영원히 똑같아야 하나?" - 달라져야 하는 것(뼈대: settings·URL·화면) → 각자 뜯어고쳐야 함 → 복사하고 관계를 끊는다 → template - 똑같아야 하는 것(공통 기능: PDF·메일) → 다 같아야 좋고 개선되면 다 받아야 함 → 설치하고 연결을 유지한다 → core

5. 버전의 함정: 배포 후에도 원본을 부를까?

Q. 실행할 때마다 core 원본/GitHub 에서 가져와? 배포 후에도?

A. 아닙니다. 아주 중요한 포인트입니다.

[pip install 시점: 딱 한 번]
GitHub 의 core → 다운로드 → 프로젝트 venv 안에 '복사본' 설치
[실행 시점: 매번]
Python 은 그 venv 안의 '복사본'에서 실행  ← GitHub 도, 원본 폴더도 안 봄

증거: 원본 폴더는 최신(0.21.0)인데 어떤 프로젝트 venv 의 설치 사본은 옛날(0.1.0)일 수 있습니다. 재설치 전까진 계속 옛 사본을 씁니다. "core 는 연결 유지"라는 말은 실시간 연결이 아니라, requirements.txt 에 원본 주소+버전을 남겨 재설치 명령 한 번으로 갱신 가능하다는 뜻입니다(느슨한 연결).

Q. 설치된 사본을 자동으로 계속 업데이트하면 안 돼?

A. 일부러 안 합니다. 그게 오히려 안전합니다. 배포된 프로그램의 제1원칙은 "어제 되던 게 오늘도 똑같이 된다". core 가 한밤중에 자동으로 바뀌면 예고 없는 고장·재현 불가·운영 사고·호환성 파손이 생깁니다. - 업계 표준 = 버전 고정(pinning) + 사람이 원할 때 수동 갱신. 그래서 @v0.20.0 태그를 박아 둡니다. - 대가: 프로젝트가 옛 버전에 뒤처질 수 있음. 그건 안정성을 얻는 대가이며, 필요할 때 태그를 바꿔 재설치 → 테스트 → 배포합니다.

6. core 거버넌스: 뭘 넣나 / 누가 정하나

무엇을 넣나: 공통 + 범용 + 안정적인 것만. 많다고 좋은 게 아닙니다. core 는 모든 프로젝트에 설치되므로, 아무거나 넣으면 다들 안 쓰는 코드까지 떠안고 불필요하게 얽힙니다.

✅ 넣을 것: "PDF 읽기" (여러 프로젝트가 다 필요, 어디서든 동일)
❌ 넣지 말 것: "특정 제품에만 쓰는 화면 로직" (그 프로젝트만 씀 → 프로젝트 안에)

Q. 누가 결정하고, 중복 개발은 어떻게 막아?

A. 결정권자 = 코어 관리자(한 명). core 는 두 겹 장치로 승인을 강제합니다: CODEOWNERS(모든 변경에 그 관리자를 자동 리뷰어로 지정) + Branch protection(master 직접 push 금지, PR → 승인 → merge). 제안은 누구나 PR 로 올리되 문지기는 한 명입니다. 애매한 부품은 처음부터 안 넣고, 두 번째 프로젝트가 필요해질 때 core 로 승격합니다(PR → 승인 → 태그 → changelog).

Q. changelog 기록은 자동이야?

A. 아닙니다. 태그를 push 한다고 저절로 써지지 않습니다. core 변경은 태그 push 후 사람이 직접 엔트리를 추가합니다(강제 훅 없는 '규율 의존' 장치). 그래서 CLAUDE.md 가 "(필수)"로 강조합니다.

마무리

핵심 정리: core 는 여러 프로젝트가 함께 쓰는 공용 기능을 한 곳(원본 하나=SSOT) 에 모아 둔 것입니다. template 처럼 복사하지 않고 pip 로 설치해서 쓰며(연결 유지), 안전을 위해 버전을 고정하고 자동 업데이트하지 않습니다. 무엇을 넣을지는 코어 관리자 승인으로 통제됩니다.
다음 시간: 네 폴더가 어떻게 맞물려 프로젝트 하나를 태어나게·자라게·정리하는지 전체를 한 번에 봅니다.