2026 Build with AI: Hands-on Campus - 내 GitHub 프로젝트 저장소를 분석하고 정리하는 AI 에이전트 만들기

#1 이전 글

[콘퍼런스] 2026 Build with AI: Hands-on Campus - 참석 후기

위의 게시글에서 이어진다.

 

#2 개요

연사 (약력)
팀장: 조예인 (25-26 GDG on Campus Sookmyung Organizer)
팀원: 송유민, 이하늘, 홍서영

키포인트
프로그램의 캐치프레이즈: "코드를 잘 쓰는 개발자보다, 코드를 더 잘 설명하는 개발자로."

AI Agent의 가장 큰 역할은 무의미한 반복 작업의 대리 수행이다. GitHub 등에 올리는 레포지토리에 README.md 파일을 매번 적는 것과 같은 일 말이다. 비슷하게, Pull requests 또한 매번 하기 번거롭다. 이 2가지를 전부 자동화하는 것이 여기서 다룰 Agent다.

 

#3 실습 로드맵

#3-1 실습 PPT

현장에서 QR 코드를 통해 PPT를 나눠주셨는데, 이 PPT가 저장된 곳이 만천하(?)에 드러난 주소라기보단 개인 저장소에 가까워 보였다. 그래서 (혹시 모르니) PPT는 첨부하지 않겠다. 대신, #4 ~ #5만 봐도 따라 하는 데에는 문제가 없다.

 

#3-2 실습용 레포지토리

GitHub - yeverycode/Agent: [25-26 GDGoC Sookmyung Build with AI] GitHub 분석 에이전트

위의 저장소를 fork한 저장소를 만들고 진행했다.

 

#4 배경 지식 & 사전 작업

#4-1 GitHub Token & 발급

어떤 GitHub 레포지토리에 접근할 수 있는 허가증. 문자열의 형태다. 아이디가 없는 비밀번호라고 봐도 좋다. AI Agent가 Pull requests를 할 때 지녀야 하기에 챙겨주어야 한다.

발급 방법은 구글 검색을 통해 알자. 이때 Token의 이름은 MY_GITHUB_TOKEN으로 짓는다. 토큰의 내용(값)은 복사해서 (남들은 볼 수 없는) 메모장 등에 붙여 놓자. 깃허브 토큰은 현재 시점 기준 "ghp_a1b2c3d4e5f6g7..."와 비슷하게 생겼다.

 

#4-2 GitHub Secret & 추가

API 키, 토큰, 비밀번호 같은 민감한 값을 GitHub에 안전하게 저장해주는 기능. 저장해두면, GitHub Actions 및 GitHub Codespace에서 참조하여 두고두고 사용할 수 있다.

[실습용 레포지토리를 fork한 저장소] - [Setting] - [Secrets and variables] - [New repository secret]의 Secret을 업데이트한다. 아래의 2가지를 추가해 주면 된다. Name을 임의로 적지 말고, 아래와 똑같이 적어야 한다. (참조: GEMINI_API_KEY 발급)

• Name: GEMINI_API_KEY
  
  • Secret: AbCdEfG...
• Name: MY_GITHUB_TOKEN
  
  • Secret: ghp_a1b2c3d4e5f6g7...

 

#4-3 GitHub Codespaces & 입장

브라우저에서 바로 열 수 있는 IDE (일반적으로 VS Code). Codespaces는 전체 프로젝트 구조의 최상단으로부터 ".devcontainer/devcontainer.json"를 읽고 어떤 환경(운영체제, 라이브러리, 환경변수, ...)에서 실행시킬지를 읽고 척척 실행해 준다.

프로그램 실행 환경을 (devcontainer.json 파일에 입력해 주는 것만으로) 손쉽게 업데이트할 수 있다. Codespaces용 VS Code에 Live Share 익스텐션을 설치하면, 같은 환경에서 + 실시간으로 + 공동 편집까지 가능하다.

 

[실습용 레포지토리를 fork한 저장소] - [Code] 탭 - [<> Code] 버튼 - [Codespace] - [Create codespace]으로 Codespace에 입장할 수 있다. 미리 입장해 두자. 그래야 Codespaces가 devcontainer.json의 내용에 맞춰 실행 환경을 준비하는 시간을 벌어 빠르게 진행할 수 있다. 우리는 한국인이니까...

 

#4-4 PyGitHub

GitHub REST API를 편하게 쓰게 해주는 라이브러리. GitHub와의 상호작용을 Python 객체 다루듯이 할 수 있다.

PyGitHub가 제공하는 대표적인 메소드는 아래와 같다. 내가 직접 메소드를 찾아보며 정리한 것이 아니라, 연사분이 일목요연하게 정리해 놓은 걸 그대로 복사해 가져온 것이다.

기능 (Action)	PyGithub 메서드	REST API 엔드포인트 (HTTP 호출)
특정 레포지토리 추출	g.get_repo()	GET /repos/{owner}/{repo}
브랜치 정보 추출	repo.get_branch()	GET /repos/{owner}/{repo}/branches/{branch}
전체 파일 트리 추출	repo.get_git_tree()	GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1
파일 내용 읽기	repo.get_contents()	GET /repos/{owner}/{repo}/contents/{path}
새 브랜치 생성	repo.create_git_ref() *	POST /repos/{owner}/{repo}/git/refs
새 브랜치 생성	repo.create_file()	PUT /repos/{owner}/{repo}/contents/{path}
파일 업데이트	repo.update_file()	PUT /repos/{owner}/{repo}/contents/{path}
PR(Pull Request) 생성	repo.create_pull()	POST /repos/{owner}/{repo}/pulls

 

#5 실습 & 분석

크게 보아 총 5단계를 거치며 프로그램이 실행된다. main.py을 보면 프로그램의 흐름을 한눈에 알 수 있다. 각 단계를 관통하는 핵심 객체는 "project_data"라는 이름의 Python dict 형 객체다. project_data에는 최종적으로 7개의 필드가 삽입된다. 단계별로 어떤 필드가 삽입되고 어떤 필드 값이 이용되는지를 따라가는 식으로 보니, 프로그램 흐름을 수월하게 읽을 수 있었다.

 

#5-1 [00] 시작

사용자가 main.py의 상수 "TARGET_REPO"와 "MODEL"에 값을 입력(하드 코딩)한 후, 터미널에 "python main.py"을 전송하여 프로그램 시작

TARGET_REPO에는 본인의 토이 프로젝트를 넣는 게 좋을 것이다. MODEL 값으로는 "gemini-3.1-flash-lite"를 사용했다. "gemini-flash-latest"를 사용하면 최신 flash 모델을 알아서 사용한다. flash 모델 말고 좀 더 무거운 모델을 사용하면, 답변 속도는 느려지지만 더 좋은 퀄리티로 응답할 것이다.

 

#5-2 [01] 정보 수집

# in main.py
...
def main():
    ...
    repo_mgr = RepoManagerAgent(token=github_token, api_key=gemini_api_key, model=MODEL)
    ...
    project_data = repo_mgr.extract_project_data(TARGET_REPO)
    ...
...

repo_manager.py 모듈을 호출해 project_data를 결괏값으로 받는다. project_data의 예시는 아래와 같다.

 

{
  "status": "success",
  "repo_name": "Kanmanemone/notion-auto-clone",
  "repo_url": "https://github.com/Kanmanemone/notion-auto-clone",
  "tree_paths": [
    ".github/workflows/run.yml",
    ".gitignore",
    "README.md",
    "custom_filter.py",
    "custom_patch.py",
    "custom_property.py",
    "main.py",
    "notion/__init__.py",
    "notion/api.py",
    "notion/filter.py",
    "notion/filter_compiler.py",
    "notion/filter_logic.py",
    "notion/property.py",
    "requirements.txt"
  ],
  "selected_files": {
    "main.py": "import os\n\nfrom custom_filter import pages_to_clone_filter, already_cloned_filter\nfrom custom_patch import source_page_patch, target_page_patch\nfrom custom_property import target_page_properties\nfrom notion.api import NotionApi\n\nnotion_api = NotionApi(os.environ[\"NOTION_TOKEN\"])\nsource_db_id = os.environ[\"SOURCE_DB_ID\"]\ntarget_db_id = os.environ[\"TARGET_DB_ID\"]\n\n# 사용자 정의 조건을 가져와 source DB에서 복제할 페이지를 조회\nsource_pages = notion_api.read(\n    db_id=source_db_id,\n    filter=pages_to_clone_filter(),\n    sorts=[\n        {\n            \"property\": \"time_order\",\n            \"direction\": \"descending\",\n        },\n    ],\n)\n\nfor source_page in source_pages[\"results\"]:\n    # source DB에서 조회한 페이지를 target DB에 새 페이지로 생성\n    already_cloned_page = notion_api.read(\n        db_id=target_db_id,\n        filter=already_cloned_filter(source_page=source_page),\n        page_size=1,\n    )\n    if already_cloned_page[\"results\"]:\n        page = already_cloned_page[\"results\"][0]\n        title = page[\"properties\"][\"name\"][\"title\"]\n        date = page[\"properties\"][\"date\"][\"formula\"][\"date\"][\"start\"]\n        print(f\"(이미 존재) {title[0]['plain_text'] if title else '(no title)'} | {date}\")\n        continue\n\n    target_page = notion_api.create(\n        db_id=target_db_id,\n        properties=target_page_properties(source_page)\n    )\n\n    # 후처리 (post process)\n    notion_api.update(page_id=source_page[\"id\"], properties=source_page_patch(source_page, target_page))\n    notion_api.update(page_id=target_page[\"id\"], properties=target_page_patch(source_page, target_page))\n\n    # 콘솔창 로그\n    title = target_page[\"properties\"][\"name\"][\"title\"]\n    print(title[0][\"plain_text\"] if title else \"(no title)\")\n",
    "notion/api.py": "import json\nimport time\nimport urllib.error\nimport urllib.request as r\nfrom typing import Any\n\nfrom notion.filter_compiler import to_notion_filter\n\n\nclass NotionApi:\n    _BASE_URL = \"https://api.notion.com/v1\"\n\n    def __init__(self, token: str):\n        # 모든 요청에 공통으로 사용할 헤더\n        self._headers = {\n            \"Authorization\": \"Bearer \" + token,\n            \"Notion-Version\": \"2022-06-28\",\n            \"Content-Type\": \"application/json\",\n        }\n\n    # Notion REST API에 HTTP 요청을 보내고 응답으로 JSON을 받는 범용 함수\n    def _api(self, method: str, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:\n        req = r.Request(\n            self._BASE_URL + path,\n            json.dumps(body).encode() if body else None,\n            self._headers,\n            method=method,\n        )\n\n        time.sleep(0.4)  # Notion API 초당 3건 제한 → 0.4초 간격 유지\n\n        wait = 1\n        for attempt in range(1, 6):  # 최대 5회 시도\n            try:\n                with r.urlopen(req) as res:\n                    return json.loads(res.read())\n\n            except urllib.error.HTTPError as e:\n                is_rate_limit = (e.code == 429)\n                is_last_attempt = (attempt == 5)\n\n                if not is_rate_limit or is_last_attempt:\n                    raise  # 429 외 에러거나 5회 모두 실패 시 그냥 던짐\n\n                # Retry-After 헤더가 있으면 그 값, 없으면 지수 백오프(1→2→4...최대 60초)\n                wait = int(e.headers.get(\"Retry-After\", wait))\n                print(f\"Rate limited. {attempt}회 시도 실패, {wait}초 후 재시도...\")\n                time.sleep(wait)\n                wait = min(wait * 2, 60)\n\n    # noinspection PyShadowingBuiltins\n    def read(\n        self,\n        db_id: str,\n        filter: dict[str, Any] | None = None,\n        page_size: int | None = None,\n        sorts: list[dict[str, str]] | None = None,\n    ) -> dict[str, Any]:\n        body: dict[str, Any] = {}\n        compiled = to_notion_filter(filter)\n        if compiled:\n            body[\"filter\"] = compiled\n        if page_size is not None:\n            body[\"page_size\"] = page_size\n        if sorts:\n            body[\"sorts\"] = sorts\n        return self._api(\"POST\", f\"/databases/{db_id}/query\", body or None)\n\n    def create(self, db_id: str, properties: dict[str, Any]) -> dict[str, Any]:\n        return self._api(\"POST\", \"/pages\", {\"parent\": {\"database_id\": db_id}, \"properties\": properties})\n\n    def update(self, page_id: str, properties: dict[str, Any]) -> dict[str, Any]:\n        return self._api(\"PATCH\", f\"/pages/{page_id}\", {\"properties\": properties})\n",
    "notion/filter_compiler.py": "import json\nfrom typing import Any\n\nfrom sympy import And, Or, Symbol\nfrom sympy.logic.boolalg import BooleanFalse, BooleanTrue, to_dnf\n\nfrom .filter_logic import and_, or_\n\n\n# custom_filter.py에서는 사람이 읽기 쉬운 중첩 and/or 조건을 작성한다.\n# Notion API는 compound filter 안에 다시 compound filter가 깊게 들어가면\n# validation_error를 반환할 수 있으므로, API 요청 직전에 DNF 형태로 펼친다.\n# 예를 들어, A AND (B OR C)를 Notion이 받기 쉬운 형태인\n# (A AND B) OR (A AND C)로 변환한다.\n\n\ndef to_notion_filter(filter_body: dict[str, Any] | None) -> dict[str, Any] | None:\n    if not filter_body:\n        return None\n\n    symbol_to_filter: dict[Symbol, dict[str, Any]] = {}\n    filter_to_symbol: dict[str, Symbol] = {}\n\n    def to_expr(item: dict[str, Any]):\n        if \"and\" in item:\n            return And(*(to_expr(child) for child in item[\"and\"]))\n        if \"or\" in item:\n            return Or(*(to_expr(child) for child in item[\"or\"]))\n\n        key = json.dumps(item, ensure_ascii=False, sort_keys=True)\n        if key not in filter_to_symbol:\n            symbol = Symbol(f\"f{len(filter_to_symbol)}\")\n            filter_to_symbol[key] = symbol\n            symbol_to_filter[symbol] = item\n        return filter_to_symbol[key]\n\n    def from_expr(expr):\n        if isinstance(expr, BooleanTrue):\n            return None\n        if isinstance(expr, BooleanFalse):\n            return None\n        if isinstance(expr, Symbol):\n            return symbol_to_filter[expr]\n        if isinstance(expr, Or):\n            return or_(*(from_expr(arg) for arg in expr.args))\n        if isinstance(expr, And):\n            return and_(*(from_expr(arg) for arg in expr.args))\n        raise TypeError(f\"Unsupported filter expression: {expr!r}\")\n\n    return from_expr(to_dnf(to_expr(filter_body), simplify=False))\n",
    "notion/filter_logic.py": "from typing import Any\n\ndef and_(*items: dict[str, Any] | None) -> dict[str, Any] | None:\n    items = [x for x in items if x]\n\n    if len(items) == 0:\n        return None\n\n    if len(items) == 1:\n        return items[0]\n\n    return {\"and\": items}\n\n\ndef or_(*items: dict[str, Any] | None) -> dict[str, Any] | None:\n    items = [x for x in items if x]\n\n    if len(items) == 0:\n        return None\n\n    if len(items) == 1:\n        return items[0]\n\n    return {\"or\": items}\n",
    "notion/property.py": "from copy import deepcopy\n\n\ndef _writable_rich_text_item(item: dict) -> dict:\n    # Notion read responses include read-only fields like plain_text, href, and expanded user data.\n    # Keep only the fields accepted by create/update rich_text payloads.\n    writable = {\"type\": item[\"type\"]}\n\n    if item[\"type\"] == \"text\":\n        writable[\"text\"] = item[\"text\"]\n    elif item[\"type\"] == \"mention\":\n        mention = item[\"mention\"]\n        mention_type = mention[\"type\"]\n        mention_value = mention[mention_type]\n\n        writable[\"mention\"] = {\"type\": mention_type}\n        if isinstance(mention_value, dict) and \"id\" in mention_value:\n            writable[\"mention\"][mention_type] = {\"id\": mention_value[\"id\"]}\n        else:\n            writable[\"mention\"][mention_type] = mention_value\n    elif item[\"type\"] == \"equation\":\n        writable[\"equation\"] = item[\"equation\"]\n\n    if \"annotations\" in item:\n        writable[\"annotations\"] = item[\"annotations\"]\n\n    return writable\n\n\ndef _writable_rich_text(content: str | list) -> str | list:\n    # Normalize rich_text copied from another page before sending it back to Notion.\n    if isinstance(content, list):\n        return [_writable_rich_text_item(deepcopy(item)) for item in content]\n    return content\n\n\nclass NotionProperties(dict):\n    \"\"\"\n    Notion property dict builder with method chaining.\n    Subclasses dict so instances can be passed directly to NotionApi.create/update.\n\n    Usage:\n        props = (\n            NotionProperties()\n            .title(\"name\", \"홍길동\")\n            .checkbox(\"is_in_guild\", True)\n            .relation(\"config\", config_page_id)\n            .number(\"level\", 260)\n            .rich_text(\"ocid\", ocid)\n            .date(\"last_api_sync_date\", \"2025-01-01\")\n            .select(\"character_relation_type\", \"bossㆍdrop\")\n        )\n        notion_api.update(page_id=..., properties=props)\n    \"\"\"\n\n    def title(self, name: str, content: str | list) -> \"NotionProperties\":\n        self[name] = {\"title\": content if isinstance(content, list) else [{\"type\": \"text\", \"text\": {\"content\": content}}]}\n        return self\n\n    def title_mention(self, name: str, page_id: str) -> \"NotionProperties\":\n        self[name] = {\"title\": [{\"type\": \"mention\", \"mention\": {\"type\": \"page\", \"page\": {\"id\": page_id}}}]}\n        return self\n\n    def rich_text(self, name: str, content: str | list) -> \"NotionProperties\":\n        content = _writable_rich_text(content)\n        self[name] = {\"rich_text\": content if isinstance(content, list) else [{\"type\": \"text\", \"text\": {\"content\": content}}]}\n        return self\n\n    def number(self, name: str, value: int | float | None) -> \"NotionProperties\":\n        self[name] = {\"number\": value}\n        return self\n\n    def checkbox(self, name: str, value: bool) -> \"NotionProperties\":\n        self[name] = {\"checkbox\": value}\n        return self\n\n    def select(self, name: str, value: str | None) -> \"NotionProperties\":\n        self[name] = {\"select\": {\"name\": value} if value is not None else None}\n        return self\n\n    def relation(self, name: str, *ids: str) -> \"NotionProperties\":\n        self[name] = {\"relation\": [{\"id\": id_} for id_ in ids]}\n        return self\n\n    def url(self, name: str, value: str | None) -> \"NotionProperties\":\n        self[name] = {\"url\": value}\n        return self\n\n    def multi_select(self, name: str, values: list) -> \"NotionProperties\":\n        self[name] = {\"multi_select\": [{\"name\": v[\"name\"]} for v in values]}\n        return self\n\n    def date(self, name: str, start: str | None, end: str | None = None) -> \"NotionProperties\":\n        if start is not None:\n            self[name] = {\"date\": {\"start\": start, \"end\": end}}\n        return self\n",
    "custom_filter.py": "from calendar import monthrange\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Any\n\nfrom notion.filter import NotionFilter as f\nfrom notion.filter_logic import and_, or_\n\n\ndef _day_start_iso(dt: datetime) -> str:\n    # Notion은 datetime 속성을 UTC 기준으로 비교하므로, date-only 대신 시각 포함 ISO 문자열 사용\n    return dt.replace(hour=0, minute=0, second=0, microsecond=0).isoformat(timespec=\"seconds\")\n\n\ndef _day_end_iso(dt: datetime) -> str:\n    return dt.replace(hour=23, minute=59, second=59, microsecond=0).isoformat(timespec=\"seconds\")\n\n\ndef already_cloned_filter(source_page: dict[str, Any]) -> dict[str, Any] | None:\n    minimum_interval_days = source_page[\"properties\"][\"minimum_interval_days\"][\"number\"]\n    if minimum_interval_days is None:\n        minimum_interval_days = 0\n\n    today = datetime.now(timezone(timedelta(hours=9)))\n    search_range_end_str = _day_end_iso(today)\n    today_start_str = _day_start_iso(today)\n    yesterday_end_str = _day_end_iso(today - timedelta(days=1))\n\n    # minimum_interval_days=7이면 14일에 clone 후 21일, 28일에 재복제 (예: 14 -> 21 -> 28)\n    # on_or_after(≥) 사용 시 경계일 당일 제외되므로 +1일 보정\n    search_range_start_str = _day_start_iso(today - timedelta(days=minimum_interval_days - 1))\n\n    return and_(\n        f.relation(name=\"schedule\", page_id=source_page[\"id\"]),\n        f.formula_date(name=\"date\", value=search_range_start_str, date_operator=\"on_or_after\"),\n        f.formula_date(name=\"date\", value=search_range_end_str, date_operator=\"on_or_before\"),\n        or_(\n            # 당일은 아직 행동 여지가 있어 '완료' 확정이 아니므로 progress 무관하게 포함\n            f.formula_date(name=\"date\", value=today_start_str, date_operator=\"on_or_after\"), # 페이지의 날짜가 오늘인가? (정확히는 오늘 이후인가?)\n            # 당일 이전(어제까지)은 progress가 '완료'여야 포함\n            and_( # 페이지가 오늘보다 이전 날짜이면서, 상태가 '완료'인가?\n                f.formula_date(name=\"date\", value=yesterday_end_str, date_operator=\"on_or_before\"),\n                f.status(name=\"progress\", value=\"완료\"),\n            ),\n        ),\n    )\n\n\ndef pages_to_clone_filter() -> dict[str, Any] | None:\n    today = datetime.now(\n        timezone(timedelta(hours=9)))  # astimezone() 대신 KST 명시: GitHub Actions는 UTC 환경이라 OS 타임존에 의존하면 날짜가 달라짐\n    today_str = today.date().isoformat()  # \"2026-05-17\" 형태. 시간 무시하고 날짜로만 비교\n    # today_str = today.isoformat(timespec=\"seconds\")  # \"2026-05-17T21:25:25+09:00\" 형태. 시각까지 비교\n\n    month = today.month\n    monthday = today.day\n    last_monthday = monthrange(today.year, month)[1]\n    week_of_month = (monthday - 1) // 7 + 1\n    last_week_of_month = (last_monthday - 1) // 7 + 1\n    weekday_value = [\"월 (mon)\", \"화 (tue)\", \"수 (wed)\", \"목 (thu)\", \"금 (fri)\", \"토 (sat)\", \"일 (sun)\"][today.weekday()]\n\n    return and_(\n        f.checkbox(\n            name=\"deprecated\",\n            value=False,\n        ),\n        f.checkbox(\n            name=\"trashed\",\n            value=False,\n        ),\n        f.checkbox(\n            name=\"auto_clone\",\n            value=True,\n        ),\n        or_(\n            and_(\n                # 날짜 범위: 시작일은 오늘 이전/당일이고, 종료일은 오늘 이후/당일인 항목\n                f.date(name=\"date\", value=_day_end_iso(today), date_operator=\"on_or_before\"),\n                f.date(name=\"_end_date\", value=_day_start_iso(today), date_operator=\"on_or_after\"),\n            ),\n            f.date(name=\"date\", value=None),\n        ),\n        or_(\n            # or로 적용되는 특수 조건\n            # TODO f.multi_select(name=\"clone_on_before_or\", values=None),\n            and_(\n                # and로 적용되는 특수 조건\n                # TODO f.multi_select(name=\"clone_on_before_and\", values=None),\n\n                # 달 (1 ~ 12), 비어 있으면 매월 반복\n                or_(\n                    f.multi_select(name=\"clone_on_month_and\", values=[str(month)]),\n                    f.multi_select(name=\"clone_on_month_and\", values=None),\n                ),\n\n                # 일 (1 ~ 31), 비어 있으면 매일 반복\n                or_(\n                    f.multi_select(name=\"clone_on_monthday_and\", values=[str(monthday)]),\n                    f.multi_select(\n                        name=\"clone_on_monthday_and\",\n                        values=[\"last_date\"],\n                    ) if monthday == last_monthday else None,\n                    f.multi_select(name=\"clone_on_monthday_and\", values=None),\n                ),\n\n                # 주차 (1 ~ 5), 비어 있으면 매주 반복\n                or_(\n                    f.multi_select(name=\"clone_on_week_of_month_and\", values=[str(week_of_month)]),\n                    f.multi_select(\n                        name=\"clone_on_week_of_month_and\",\n                        values=[\"last_week\"],\n                    ) if week_of_month == last_week_of_month else None,\n                    f.multi_select(name=\"clone_on_week_of_month_and\", values=None),\n                ),\n\n                # 요일 (월 ~ 일), 비어 있으면 매일 반복\n                or_(\n                    f.multi_select(name=\"clone_on_weekday_and\", values=[weekday_value]),\n                    f.multi_select(name=\"clone_on_weekday_and\", values=None),\n                ),\n            ),\n        ),\n    )\n",
    "custom_property.py": "from datetime import datetime, timedelta, timezone\nfrom typing import Any\n\nfrom notion.property import NotionProperties\n\n_now = datetime.now(\n    timezone(timedelta(hours=9)))  # astimezone() 대신 KST 명시: GitHub Actions는 UTC 환경이라 OS 타임존에 의존하면 날짜가 달라짐\n_iso = _now.isocalendar()\n_weekday_str = [\"월 (mon)\", \"화 (tue)\", \"수 (wed)\", \"목 (thu)\", \"금 (fri)\", \"토 (sat)\", \"일 (sun)\"][_now.weekday()]\n\n\ndef target_page_properties(source_page: dict[str, Any]) -> NotionProperties:\n    props = (\n        NotionProperties()\n        .relation(\"schedule\", source_page[\"id\"])\n        .title_mention(\"name\", source_page[\"id\"])\n        .rich_text(\"memo\", source_page[\"properties\"][\"memo\"][\"rich_text\"])\n        .rich_text(\"place\", source_page[\"properties\"][\"place\"][\"rich_text\"])\n        .relation(\"people\", *[p[\"id\"] for p in source_page[\"properties\"][\"people\"][\"relation\"]])\n        .number(\"duration_hour\", 0)\n        .number(\"_source_year\", _iso.year)\n        .number(\"_source_week_of_year\", _iso.week)\n        .select(\"_source_day_of_week\", _weekday_str)\n    )\n    return props\n",
    ".github/workflows/run.yml": "on:\n  workflow_dispatch:\n  schedule:\n    # 매일 한국시간 00:22 실행\n    # KST 00:22 = UTC 전날 15:22\n    - cron: \"22 15 * * *\"\n\njobs:\n  r:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n      - run: python3 -m pip install -r requirements.txt\n      - run: python3 main.py\n        env:\n          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}\n          SOURCE_DB_ID: ${{ secrets.SOURCE_DB_ID }}\n          TARGET_DB_ID: ${{ secrets.TARGET_DB_ID }}\n"
  }
}

tree_paths에 프로젝트의 전체 구조가 담긴다. selected_files에는 해당 레포지토리를 대표하는 파일을 최대 10개까지 담기는데, 소스 코드까지 가져온다.

 

#5-3 [02] 구조 해석

# in main.py
...
def main():
    ...
    analyst = AnalystAgent(api_key=gemini_api_key, model=MODEL)
    ...
    analyst_output = analyst.run(project_data)
    ...
    project_data["analysis_summary"] = ... analyst_output.get("analysis_result", "{}") ...
...

ananalyst.py 모듈을 호출해 analyst_output을 결괏값으로 받는다. analyst_output의 일부 데이터는 analysis_summary라는 key 이름으로 project_data에 추가되고, 나머지 데이터는 [03] 키워드 추출 단계에서 사용된다. analyst_output의 예시는 아래와 같다.

 

{
  "status": "success",
  "repo_name": "Kanmanemone/notion-auto-clone",
  "repo_url": "https://github.com/Kanmanemone/notion-auto-clone",
  "candidate_files": ["README.md", "requirements.txt", "main.py"],
  "structure_summary": {
    "top_directories": {
      "notion": 6,
      ".github": 1
    },
    "important_root_files": ["README.md", "requirements.txt"],
    "extension_summary": {
      "py": 10,
      "yml": 1,
      "gitignore": 1,
      "md": 1,
      "txt": 1
    },
    "total_paths": 14
  },
  "structure_hints": {
    "has_frontend": false,
    "has_backend": false,
    "has_components_dir": false,
    "has_pages_dir": false,
    "has_api_dir": false,
    "has_docker": false,
    "has_readme": true,
    "possible_framework_files": ["requirements.txt"]
  },
  "analysis_context": "=== REPOSITORY META ===\nRepository name: Kanmanemone/notion-auto-clone\nRepository URL: https://github.com/Kanmanemone/notion-auto-clone\n\n=== TREE SUMMARY ===\nTotal paths: 14\nTop directories: {'notion': 6, '.github': 1}\nImportant root files: ['README.md', 'requirements.txt']\nExtension summary: {'py': 10, 'yml': 1, 'gitignore': 1, 'md': 1, 'txt': 1}\n\n=== STRUCTURE HINTS ===\n{'has_frontend': False, 'has_backend': False, 'has_components_dir': False, 'has_pages_dir': False, 'has_api_dir': False, 'has_docker': False, 'has_readme': True, 'possible_framework_files': ['requirements.txt']}\n\n=== REPOSITORY TREE (partial) ===\n.github/workflows/run.yml\n.gitignore\nREADME.md\ncustom_filter.py\ncustom_patch.py\ncustom_property.py\nmain.py\nnotion/__init__.py\nnotion/api.py\nnotion/filter.py\nnotion/filter_compiler.py\nnotion/filter_logic.py\nnotion/property.py\nrequirements.txt\n\n=== SELECTED FILE CONTENTS ===\n\n--- FILE: main.py ---\nimport os\n\nfrom custom_filter import pages_to_clone_filter, already_cloned_filter\nfrom custom_patch import source_page_patch, target_page_patch\nfrom custom_property import target_page_properties\nfrom notion.api import NotionApi\n\nnotion_api = NotionApi(os.environ[\"NOTION_TOKEN\"])\nsource_db_id = os.environ[\"SOURCE_DB_ID\"]\ntarget_db_id = os.environ[\"TARGET_DB_ID\"]\n\n# 사용자 정의 조건을 가져와 source DB에서 복제할 페이지를 조회\nsource_pages = notion_api.read(\n    db_id=source_db_id,\n    filter=pages_to_clone_filter(),\n    sorts=[\n        {\n            \"property\": \"time_order\",\n            \"direction\": \"descending\",\n        },\n    ],\n)\n\nfor source_page in source_pages[\"results\"]:\n    # source DB에서 조회한 페이지를 target DB에 새 페이지로 생성\n    already_cloned_page = notion_api.read(\n        db_id=target_db_id,\n        filter=already_cloned_filter(source_page=source_page),\n        page_size=1,\n    )\n    if already_cloned_page[\"results\"]:\n        page = already_cloned_page[\"results\"][0]\n        title = page[\"properties\"][\"name\"][\"title\"]\n        date = page[\"properties\"][\"date\"][\"formula\"][\"date\"][\"start\"]\n        print(f\"(이미 존재) {title[0]['plain_text'] if title else '(no title)'} | {date}\")\n        continue\n\n    target_page = notion_api.create(\n        db_id=target_db_id,\n        properties=target_page_properties(source_page)\n    )\n\n    # 후처리 (post process)\n    notion_api.update(page_id=source_page[\"id\"], properties=source_page_patch(source_page, target_page))\n    notion_api.update(page_id=target_page[\"id\"], properties=target_page_patch(source_page, target_page))\n\n    # 콘솔창 로그\n    title = target_page[\"properties\"][\"name\"][\"title\"]\n    print(title[0][\"plain_text\"] if title else \"(no title)\")\n\n\n--- FILE: notion/api.py ---\nimport json\nimport time\nimport urllib.error\nimport urllib.request as r\nfrom typing import Any\n\nfrom notion.filter_compiler import to_notion_filter\n\n\nclass NotionApi:\n    _BASE_URL = \"https://api.notion.com/v1\"\n\n    def __init__(self, token: str):\n        # 모든 요청에 공통으로 사용할 헤더\n        self._headers = {\n            \"Authorization\": \"Bearer \" + token,\n            \"Notion-Version\": \"2022-06-28\",\n            \"Content-Type\": \"application/json\",\n        }\n\n    # Notion REST API에 HTTP 요청을 보내고 응답으로 JSON을 받는 범용 함수\n    def _api(self, method: str, path: str, body: dict[str, Any] | None = None) -> dict[str, Any]:\n        req = r.Request(\n            self._BASE_URL + path,\n            json.dumps(body).encode() if body else None,\n            self._headers,\n            method=method,\n        )\n\n        time.sleep(0.4)  # Notion API 초당 3건 제한 → 0.4초 간격 유지\n\n        wait = 1\n        for attempt in range(1, 6):  # 최대 5회 시도\n            try:\n                with r.urlopen(req) as res:\n                    return json.loads(res.read())\n\n            except urllib.error.HTTPError as e:\n                is_rate_limit = (e.code == 429)\n                is_last_attempt = (attempt == 5)\n\n                if not is_rate_limit or is_last_attempt:\n                    raise  # 429 외 에러거나 5회 모두 실패 시 그냥 던짐\n\n                # Retry-After 헤더가 있으면 그 값, 없으면 지수 백오프(1→2→4...최대 60초)\n                wait = int(e.headers.get(\"Retry-After\", wait))\n                print(f\"Rate limited. {attempt}회 시도 실패, {wait}초 후 재시도...\")\n                time.sleep(wait)\n                wait = min(wait * 2, 60)\n\n    # noinspection PyShadowingBuiltins\n    def read(\n        self,\n        db_id: str,\n        filter: dict[str, Any] | None = None,\n        page_size: int | None = None,\n        sorts: list[dict[str, str]] | None = None,\n    ) -> dict[str, Any]:\n        body: dict[str, Any] = {}\n        compiled = to_notion_filter(filter)\n        if compiled:\n            body[\"filter\"] = compiled\n        if page_size is not None:\n            body[\"page_size\"] = page_size\n        if sorts:\n            body[\"sorts\"] = sorts\n        return self._api(\"POST\", f\"/databases/{db_id}/query\", body or None)\n\n    def create(self, db_id: str, properties: dict[str, Any]) -> dict[str, Any]:\n        return self._api(\"POST\", \"/pages\", {\"parent\": {\"database_id\": db_id}, \"properties\": properties})\n\n    def update(self, page_id: str, properties: dict[str, Any]) -> dict[str, Any]:\n        return self._api(\"PATCH\", f\"/pages/{page_id}\", {\"properties\": properties})\n\n\n--- FILE: notion/filter_compiler.py ---\nimport json\nfrom typing import Any\n\nfrom sympy import And, Or, Symbol\nfrom sympy.logic.boolalg import BooleanFalse, BooleanTrue, to_dnf\n\nfrom .filter_logic import and_, or_\n\n\n# custom_filter.py에서는 사람이 읽기 쉬운 중첩 and/or 조건을 작성한다.\n# Notion API는 compound filter 안에 다시 compound filter가 깊게 들어가면\n# validation_error를 반환할 수 있으므로, API 요청 직전에 DNF 형태로 펼친다.\n# 예를 들어, A AND (B OR C)를 Notion이 받기 쉬운 형태인\n# (A AND B) OR (A AND C)로 변환한다.\n\n\ndef to_notion_filter(filter_body: dict[str, Any] | None) -> dict[str, Any] | None:\n    if not filter_body:\n        return None\n\n    symbol_to_filter: dict[Symbol, dict[str, Any]] = {}\n    filter_to_symbol: dict[str, Symbol] = {}\n\n    def to_expr(item: dict[str, Any]):\n        if \"and\" in item:\n            return And(*(to_expr(child) for child in item[\"and\"]))\n        if \"or\" in item:\n            return Or(*(to_expr(child) for child in item[\"or\"]))\n\n        key = json.dumps(item, ensure_ascii=False, sort_keys=True)\n        if key not in filter_to_symbol:\n            symbol = Symbol(f\"f{len(filter_to_symbol)}\")\n            filter_to_symbol[key] = symbol\n            symbol_to_filter[symbol] = item\n        return filter_to_symbol[key]\n\n    def from_expr(expr):\n        if isinstance(expr, BooleanTrue):\n            return None\n        if isinstance(expr, BooleanFalse):\n            return None\n        if isinstance(expr, Symbol):\n            return symbol_to_filter[expr]\n        if isinstance(expr, Or):\n            return or_(*(from_expr(arg) for arg in expr.args))\n        if isinstance(expr, And):\n            return and_(*(from_expr(arg) for arg in expr.args))\n        raise TypeError(f\"Unsupported filter expression: {expr!r}\")\n\n    return from_expr(to_dnf(to_expr(filter_body), simplify=False))\n\n\n--- FILE: notion/filter_logic.py ---\nfrom typing import Any\n\ndef and_(*items: dict[str, Any] | None) -> dict[str, Any] | None:\n    items = [x for x in items if x]\n\n    if len(items) == 0:\n        return None\n\n    if len(items) == 1:\n        return items[0]\n\n    return {\"and\": items}\n\n\ndef or_(*items: dict[str, Any] | None) -> dict[str, Any] | None:\n    items = [x for x in items if x]\n\n    if len(items) == 0:\n        return None\n\n    if len(items) == 1:\n        return items[0]\n\n    return {\"or\": items}\n\n\n--- FILE: notion/property.py ---\nfrom copy import deepcopy\n\n\ndef _writable_rich_text_item(item: dict) -> dict:\n    # Notion read responses include read-only fields like plain_text, href, and expanded user data.\n    # Keep only the fields accepted by create/update rich_text payloads.\n    writable = {\"type\": item[\"type\"]}\n\n    if item[\"type\"] == \"text\":\n        writable[\"text\"] = item[\"text\"]\n    elif item[\"type\"] == \"mention\":\n        mention = item[\"mention\"]\n        mention_type = mention[\"type\"]\n        mention_value = mention[mention_type]\n\n        writable[\"mention\"] = {\"type\": mention_type}\n        if isinstance(mention_value, dict) and \"id\" in mention_value:\n            writable[\"mention\"][mention_type] = {\"id\": mention_value[\"id\"]}\n        else:\n            writable[\"mention\"][mention_type] = mention_value\n    elif item[\"type\"] == \"equation\":\n        writable[\"equation\"] = item[\"equation\"]\n\n    if \"annotations\" in item:\n        writable[\"annotations\"] = item[\"annotations\"]\n\n    return writable\n\n\ndef _writable_rich_text(content: str | list) -> str | list:\n    # Normalize rich_text copied from another page before sending it back to Notion.\n    if isinstance(content, list):\n        return [_writable_rich_text_item(deepcopy(item)) for item in content]\n    return content\n\n\nclass NotionProperties(dict):\n    \"\"\"\n    Notion property dict builder with method chaining.\n    Subclasses dict so instances can be passed directly to NotionApi.create/update.\n\n    Usage:\n        props = (\n            NotionProperties()\n            .title(\"name\", \"홍길동\")\n            .checkbox(\"is_in_guild\", True)\n            .relation(\"config\", config_page_id)\n            .number(\"level\", 260)\n            .rich_text(\"ocid\", ocid)\n            .date(\"last_api_sync_date\", \"2025-01-01\")\n            .select(\"character_relation_type\", \"bossㆍdrop\")\n        )\n        notion_api.update(page_id=..., properties=props)\n    \"\"\"\n\n    def title(self, name: str, content: str | list) -> \"NotionProperties\":\n        self[name] = {\"title\": content if isinstance(content, list) else [{\"type\": \"text\", \"text\": {\"content\": content}}]}\n        return self\n\n    def title_mention(self, name: str, page_id: str) -> \"NotionProperties\":\n        self[name] = {\"title\": [{\"type\": \"mention\", \"mention\": {\"type\": \"page\", \"page\": {\"id\": page_id}}}]}\n        return self\n\n    def rich_text(self, name: str, content: str | list) -> \"NotionProperties\":\n        content = _writable_rich_text(content)\n        self[name] = {\"rich_text\": content if isinstance(content, list) else [{\"type\": \"text\", \"text\": {\"content\": content}}]}\n        return self\n\n    def number(self, name: str, value: int | float | None) -> \"NotionProperties\":\n        self[name] = {\"number\": value}\n        return self\n\n    def checkbox(self, name: str, value: bool) -> \"NotionProperties\":\n        self[name] = {\"checkbox\": value}\n        return self\n\n    def select(self, name: str, value: str | None) -> \"NotionProperties\":\n        self[name] = {\"select\": {\"name\": value} if value is not None else None}\n        return self\n\n    def relation(self, name: str, *ids: str) -> \"NotionProperties\":\n        self[name] = {\"relation\": [{\"id\": id_} for id_ in ids]}\n        return self\n\n    def url(self, name: str, value: str | None) -> \"NotionProperties\":\n        self[name] = {\"url\": value}\n        return self\n\n    def multi_select(self, name: str, values: list) -> \"NotionProperties\":\n        self[name] = {\"multi_select\": [{\"name\": v[\"name\"]} for v in values]}\n        return self\n\n    def date(self, name: str, start: str | None, end: str | None = None) -> \"NotionProperties\":\n        if start is not None:\n            self[name] = {\"date\": {\"start\": start, \"end\": end}}\n        return self\n\n\n--- FILE: custom_filter.py ---\nfrom calendar import monthrange\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Any\n\nfrom notion.filter import NotionFilter as f\nfrom notion.filter_logic import and_, or_\n\n\ndef _day_start_iso(dt: datetime) -> str:\n    # Notion은 datetime 속성을 UTC 기준으로 비교하므로, date-only 대신 시각 포함 ISO 문자열 사용\n    return dt.replace(hour=0, minute=0, second=0, microsecond=0).isoformat(timespec=\"seconds\")\n\n\ndef _day_end_iso(dt: datetime) -> str:\n    return dt.replace(hour=23, minute=59, second=59, microsecond=0).isoformat(timespec=\"seconds\")\n\n\ndef already_cloned_filter(source_page: dict[str, Any]) -> dict[str, Any] | None:\n    minimum_interval_days = source_page[\"properties\"][\"minimum_interval_days\"][\"number\"]\n    if minimum_interval_days is None:\n        minimum_interval_days = 0\n\n    today = datetime.now(timezone(timedelta(hours=9)))\n    search_range_end_str = _day_end_iso(today)\n    today_start_str = _day_start_iso(today)\n    yesterday_end_str = _day_end_iso(today - timedelta(days=1))\n\n    # minimum_interval_days=7이면 14일에 clone 후 21일, 28일에 재복제 (예: 14 -> 21 -> 28)\n    # on_or_after(≥) 사용 시 경계일 당일 제외되므로 +1일 보정\n    search_range_start_str = _day_start_iso(today - timedelta(days=minimum_interval_days - 1))\n\n    return and_(\n        f.relation(name=\"schedule\", page_id=source_page[\"id\"]),\n        f.formula_date(name=\"date\", value=search_range_start_str, date_operator=\"on_or_after\"),\n        f.formula_date(name=\"date\", value=search_range_end_str, date_operator=\"on_or_before\"),\n        or_(\n            # 당일은 아직 행동 여지가 있어 '완료' 확정이 아니므로 progress 무관하게 포함\n            f.formula_date(name=\"date\", value=today_start_str, date_operator=\"on_or_after\"), # 페이지의 날짜가 오늘인가? (정확히는 오늘 이후인가?)\n            # 당일 이전(어제까지)은 progress가 '완료'여야 포함\n            and_( # 페이지가 오늘보다 이전 날짜이면서, 상태가 '완료'인가?\n                f.formula_date(name=\"date\", value=yesterday_end_str, date_operator=\"on_or_before\"),\n                f.status(name=\"progress\", value=\"완료\"),\n            ),\n        ),\n    )\n\n\ndef pages_to_clone_filter() -> dict[str, Any] | None:\n    today = datetime.now(\n        timezone(timedelta(hours=9)))  # astimezone() 대신 KST 명시: GitHub Actions는 UTC 환경이라 OS 타임존에 의존하면 날짜가 달라짐\n    today_str = today.date().isoformat()  # \"2026-05-17\" 형태. 시간 무시하고 날짜로만 비교\n    # today_str = today.isoformat(timespec=\"seconds\")  # \"2026-05-17T21:25:25+09:00\" 형태. 시각까지 비교\n\n    month = today.month\n    monthday = today.day\n    last_monthday = monthrange(today.year, month)[1]\n    week_of_month = (monthday - 1) // 7 + 1\n    last_week_of_month = (last_monthday - 1) // 7 + 1\n    weekday_value = [\"월 (mon)\", \"화 (tue)\", \"수 (wed)\", \"목 (thu)\", \"금 (fri)\", \"토 (sat)\", \"일 (sun)\"][today.weekday()]\n\n    return and_(\n        f.checkbox(\n            name=\"deprecated\",\n            value=False,\n        ),\n        f.checkbox(\n            name=\"trashed\",\n            value=False,\n        ),\n        f.checkbox(\n            name=\"auto_clone\",\n            value=True,\n        ),\n        or_(\n            and_(\n                # 날짜 범위: 시작일은 오늘 이전/당일이고, 종료일은 오늘 이후/당일인 항목\n                f.date(name=\"date\", value=_day_end_iso(today), date_operator=\"on_or_before\"),\n                f.date(name=\"_end_date\", value=_day_start_iso(today), date_operator=\"on_or_after\"),\n            ),\n            f.date(name=\"date\", value=None),\n        ),\n        or_(\n            # or로 적용되는 특수 조건\n            # TODO f.multi_select(name=\"clone_on_before_or\", values=None),\n            and_(\n                # and로 적용되는 특수 조건\n                # TODO f.multi_select(name=\"clone_on_before_and\", values=None),\n\n                # 달 (1 ~ 12), 비어 있으면 매월 반복\n                or_(\n                    f.multi_select(name=\"clone_on_month_and\", values=[str(month)]),\n                    f.multi_select(name=\"clone_on_month_and\", values=None),\n                ),\n\n                # 일 (1 ~ 31), 비어 있으면 매일 반복\n                or_(\n                    f.multi_select(name=\"clone_on_monthday_and\", values=[str(monthday)]),\n                    f.multi_select(\n                       \n\n--- FILE: custom_property.py ---\nfrom datetime import datetime, timedelta, timezone\nfrom typing import Any\n\nfrom notion.property import NotionProperties\n\n_now = datetime.now(\n    timezone(timedelta(hours=9)))  # astimezone() 대신 KST 명시: GitHub Actions는 UTC 환경이라 OS 타임존에 의존하면 날짜가 달라짐\n_iso = _now.isocalendar()\n_weekday_str = [\"월 (mon)\", \"화 (tue)\", \"수 (wed)\", \"목 (thu)\", \"금 (fri)\", \"토 (sat)\", \"일 (sun)\"][_now.weekday()]\n\n\ndef target_page_properties(source_page: dict[str, Any]) -> NotionProperties:\n    props = (\n        NotionProperties()\n        .relation(\"schedule\", source_page[\"id\"])\n        .title_mention(\"name\", source_page[\"id\"])\n        .rich_text(\"memo\", source_page[\"properties\"][\"memo\"][\"rich_text\"])\n        .rich_text(\"place\", source_page[\"properties\"][\"place\"][\"rich_text\"])\n        .relation(\"people\", *[p[\"id\"] for p in source_page[\"properties\"][\"people\"][\"relation\"]])\n        .number(\"duration_hour\", 0)\n        .number(\"_source_year\", _iso.year)\n        .number(\"_source_week_of_year\", _iso.week)\n        .select(\"_source_day_of_week\", _weekday_str)\n    )\n    return props\n\n\n--- FILE: custom_patch.py ---\nfrom typing import Any\n\n\ndef source_page_patch(source_page: dict[str, Any], target_page: dict[str, Any]) -> dict[str, Any]:\n    # TODO\n\n    return {}\n\n\ndef target_page_patch(source_page: dict[str, Any], target_page: dict[str, Any]) -> dict[str, Any]:\n    #TODO\n\n    return {}\n\n\n--- FILE: .github/workflows/run.yml ---\non:\n  workflow_dispatch:\n  schedule:\n    # 매일 한국시간 00:22 실행\n    # KST 00:22 = UTC 전날 15:22\n    - cron: \"22 15 * * *\"\n\njobs:\n  r:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v5\n      - run: python3 -m pip install -r requirements.txt\n      - run: python3 main.py\n        env:\n          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}\n          SOURCE_DB_ID: ${{ secrets.SOURCE_DB_ID }}\n          TARGET_DB_ID: ${{ secrets.TARGET_DB_ID }}\n",
  "analysis_result": "{\n    \"project_overview\": \"Notion의 특정 데이터베이스(Source DB)에 정의된 반복 일정이나 작업을 조건에 맞춰 다른 데이터베이스(Target DB)로 자동으로 복제해주는 자동화 도구입니다. GitHub Actions를 통해 정기적으로 실행되며, 사용자가 정의한 복잡한 필터링 로직에 따라 페이지를 생성하고 관계형 정보를 동기화합니다.\",\n    \"directory_structure\": \"프로젝트는 파이썬 기반으로 구성되어 있으며, 'notion/' 디렉토리 내에 Notion REST API 호출을 위한 핵심 모듈(api, 필터 로직, 속성 빌더)이 위치합니다. 루트 디렉토리의 파일들(custom_*.py)은 사용자 정의 비즈니스 로직을 담당하며, '.github/' 디렉토리는 배포 및 자동 실행을 위한 CI/CD 설정을 포함합니다.\",\n    \"key_features\": [\n        \"Notion API를 활용한 데이터베이스 자동 읽기/쓰기 및 페이지 복제\",\n        \"SymPy 라이브러리를 활용한 복잡한 Notion 필터(AND/OR 조건)의 DNF 변환 및 쿼리 최적화\",\n        \"GitHub Actions를 이용한 매일 특정 시간(KST 기준) 반복 작업 수행\",\n        \"Rate Limit(429) 대응을 위한 재시도 로직 및 지수 백오프 적용\",\n        \"Method Chaining을 활용한 직관적인 Notion 페이지 속성 빌더 제공\"\n    ],\n    \"key_files\": {\n        \"main.py\": \"프로젝트의 진입점. Source DB에서 대상 페이지를 조회하고, 중복 여부를 체크한 뒤 Target DB에 페이지를 생성하고 후처리를 수행합니다.\",\n        \"notion/api.py\": \"Notion REST API와의 통신을 관리하며, 요청 헤더 설정, 에러 처리, Rate Limit 대응(재시도) 로직을 포함합니다.\",\n        \"notion/filter_compiler.py\": \"사람이 작성한 중첩된 필터 조건을 Notion API가 이해할 수 있는 형태로 변환합니다. 논리식 단순화 및 API 요청 제약 대응을 수행합니다.\",\n        \"notion/property.py\": \"Notion의 복잡한 속성 JSON 구조를 쉽게 작성할 수 있도록 돕는 'NotionProperties' 빌더 클래스를 제공합니다.\",\n        \"custom_filter.py\": \"사용자의 특정 비즈니스 요구사항(예: 주간/월간 반복 일정 체크)에 따른 페이지 선정 로직을 담고 있습니다.\"\n    },\n    \"execution_flow\": \"1. GitHub Actions 스케줄러가 매일 지정된 시간에 워크플로우를 트리거함. 2. 'main.py'가 실행되어 환경 변수에서 토큰과 DB ID를 로드함. 3. 'custom_filter.py'를 통해 복제 대상 페이지를 필터링함. 4. 각 페이지에 대해 'Target DB'에 이미 복제되었는지 확인. 5. 복제되지 않았다면 'custom_property.py'를 통해 속성을 구성하여 페이지를 생성. 6. 완료 후 로그 출력 및 후처리 업데이트 수행.\",\n    \"uncertain_points\": \"1. 'custom_patch.py' 파일 내의 'source_page_patch'와 'target_page_patch' 함수가 'TODO'로 비어있어, 복제 이후 페이지 간 상태 동기화나 상호 업데이트 기능은 현재 구현되지 않았거나 미완성 상태로 추정됩니다. 2. 사용자 정의 필터의 복잡도에 따라 Notion의 최대 필터 깊이 제한 이슈가 완벽히 해결되었는지 추가 검증이 필요할 수 있습니다.\"\n}"
}

candidate_files은 tree_paths에서 '분석할 가치가 있는' 파일을 최대 8개까지 골라낸 목록이다. structure_summary는 프로젝트의 전체 폴더 구조를 요약한 것이다. structure_hints는 src/App.tsx가 있으면 React + TypeScript인 것처럼, 어떤 프로젝트인지를 결정하는 단서(hint)를 뽑아낸다. analysis_context는 (더욱 정확한) analysis_result 도출을 위해 LLM 모델에게 전달할 프롬프트를 생성한다. analysis_result는 project_data의 analysis_summary를 만들기 위한 최종 재료다.

 

#5-4 [03] 키워드 추출

# in main.py
...
def main():
    ...
    tech_exp = TechExpertAgent(api_key=gemini_api_key, model=MODEL)
    ...
    analyst_output = analyst.run(project_data)
    ...
    tech_output = tech_exp.run(analyst_output)
    ...
    project_data["tech_summary"] = tech_output.get("tech_summary")
    ...
...

tech_expert.py 모듈을 호출해 tech_output을 결괏값으로 받는다. tech_output의 tech_summary는 똑같은 이름인 tech_summary라는 key 이름으로 project_data에 추가된다. tech_output의 예시는 아래와 같다.

 

{
  "status": "success",
  "tech_summary": {
    "tech_stack": {
      "Backend": [
        "Python (Notion API를 활용한 자동화 로직 구현에 적합한 가독성과 풍부한 라이브러리를 제공합니다)",
        "SymPy (복잡한 논리식(DNF 변환)을 수학적으로 해석하여 Notion API의 필터 제약을 유연하게 해결합니다)"
      ],
      "Database": [
        "Notion Database (구조화된 데이터를 API로 손쉽게 관리하고 시각화할 수 있는 유연한 노코드 DB를 활용합니다)"
      ],
      "DevOps": [
        "GitHub Actions (별도의 서버 구축 없이도 클라우드 환경에서 스케줄링된 자동화 작업을 안정적으로 실행합니다)"
      ]
    },
    "architecture_summary": "GitHub Actions를 통해 매일 특정 시간에 구동되는 Python 기반의 스크립트가 Notion REST API를 활용하여 소스 데이터베이스의 필터링 된 페이지를 타겟 데이터베이스에 복제하고, 생성된 페이지를 상호 참조(Patch)하여 동기화하는 자동화 시스템입니다.",
    "mermaid_code": "graph TD\n    classDef backend fill:#D4E6F1,stroke:#3498DB,stroke-width:2px;\n    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;\n    classDef storage fill:#D1F2EB,stroke:#2ECC71,stroke-width:2px;\n    classDef user fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;\n\n    github_action[\"GitHub Actions (Scheduler)\"]:::external\n    main_py[\"main.py (Automation Logic)\"]:::backend\n    notion_api[\"Notion REST API\"]:::external\n    notion_db_source[\"Source Notion Database\"]:::storage\n    notion_db_target[\"Target Notion Database\"]:::storage\n\n    github_action -- \"매일 정시 실행\" --> main_py\n    main_py -- \"데이터 조회 (Read)\" --> notion_db_source\n    main_py -- \"API 요청\" --> notion_api\n    notion_api -- \"결과 반환\" --> main_py\n    main_py -- \"데이터 복제/생성 (Create/Update)\" --> notion_db_target",
    "key_points": [
      "SymPy를 이용한 필터 쿼리 DNF(이장규정형) 변환으로 Notion API의 복잡한 중첩 필터 제한 우회",
      "Rate Limit 대응을 위해 지수 백오프 전략 및 429 에러 핸들링 로직 구현",
      "GitHub Actions 환경의 UTC 타임존 문제를 KST로 명시하여 날짜 기반 스케줄링 정확도 확보",
      "클래스 기반의 Property 빌더를 사용하여 Notion의 복잡한 JSON 구조를 가독성 높은 체이닝 패턴으로 단순화"
    ]
  }
}

사실상 tech_summary == tech_output이라고 할 수 있겠다 (status 무시).

 

#5-5 [04] README.md 제작

# in main.py
...
def main():
    ...
    writer = WriterAgent(api_key=gemini_api_key, model=MODEL, mode="portfolio")
    ...
    writer_output = writer.run(project_data)
    ...
    final_readme = writer_output.get("readme_markdown")
    ...
...

writers.py 모듈을 호출해 writer_output을 결괏값으로 받는다. writer_output은 지금까지 만든 project_data를 통해, REAMD.md를 만들어낸다. writer_output의 예시는 아래와 같다.

 

{
  "status": "success",
  "readme_markdown": "# Notion Auto Clone\n\nNotion 데이터베이스 간의 데이터를 자동으로 동기화하고 복제하는 파이썬 기반의 자동화 도구입니다. 복잡한 필터링 로직과 Notion API의 제약 사항을 효율적으로 해결하여 데이터 관리의 생산성을 높이는 데 목적이 있습니다.\n\n## 프로젝트 소개\n본 프로젝트는 Notion 데이터베이스 내의 특정 페이지를 자동으로 추출하여 다른 데이터베이스로 복제하고 관리하는 자동화 스크립트입니다. GitHub Actions를 활용해 별도의 서버 구축 없이 주기적인 데이터 동기화 파이프라인을 구축할 수 있습니다.\n\n## 주요 기능\n- **자동화된 데이터 동기화**: 소스 DB에서 조건에 맞는 데이터를 추출하여 타겟 DB로 복제.\n- **복잡한 필터 쿼리 처리**: SymPy를 이용한 DNF(이장규정형) 변환으로 Notion API의 필터 중첩 제한 우회.\n- **API 안정성 확보**: 지수 백오프 전략 및 429 에러(Rate Limit) 대응 로직 구현.\n- **직관적인 속성 관리**: 클래스 기반 빌더 패턴으로 Notion의 복잡한 JSON 구조를 가독성 있게 작성.\n\n## 시스템 아키텍처\n```mermaid\ngraph TD\n    classDef backend fill:#D4E6F1,stroke:#3498DB,stroke-width:2px;\n    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;\n    classDef storage fill:#D1F2EB,stroke:#2ECC71,stroke-width:2px;\n\n    github_action[\"GitHub Actions (Scheduler)\"]:::external\n    main_py[\"main.py (Automation Logic)\"]:::backend\n    notion_api[\"Notion REST API\"]:::external\n    notion_db_source[\"Source Notion Database\"]:::storage\n    notion_db_target[\"Target Notion Database\"]:::storage\n\n    github_action -- \"매일 정시 실행\" --> main_py\n    main_py -- \"데이터 조회 (Read)\" --> notion_db_source\n    main_py -- \"API 요청\" --> notion_api\n    notion_api -- \"결과 반환\" --> main_py\n    main_py -- \"데이터 복제/생성 (Create/Update)\" --> notion_db_target\n```\n\n## 프로젝트 구조 및 핵심 파일\n```text\n.\n├── main.py              # 프로젝트 진입점, 데이터 조회 및 동기화 흐름 제어\n├── custom_filter.py     # 사용자의 비즈니스 로직(반복 일정 등)에 따른 필터 선정\n├── notion/\n│   ├── api.py           # Notion REST API 통신 및 에러 핸들링\n│   ├── filter_compiler.py # 복잡한 필터 조건을 API 형식으로 변환\n│   └── property.py      # Notion 속성 JSON 빌더 클래스\n```\n\n## 기술 스택\n- **Backend**: Python (가독성과 풍부한 라이브러리를 통한 API 자동화 구현)\n- **Library**: SymPy (복잡한 논리식 해석 및 Notion API 필터 제약 해결)\n- **Database**: Notion Database (유연한 구조화와 API 접근성을 갖춘 노코드 DB)\n- **DevOps**: GitHub Actions (서버 비용 없이 클라우드 환경에서 자동화 작업 스케줄링)\n\n## 기술 선택 이유\n- **Python**: API 연동 및 데이터 처리 로직을 직관적으로 작성하기에 가장 효율적입니다.\n- **SymPy**: 중첩 필터 제약을 수학적으로 최적화하여 복잡한 비즈니스 조건 처리를 가능하게 합니다.\n- **GitHub Actions**: 클라우드 기반의 간편한 CI/CD 환경을 제공하여 스케줄링을 안정적으로 운영할 수 있습니다.\n\n## 실행 방법\n*추가 작성 필요* (현재 저장소 내 구체적인 실행 가이드가 포함되어 있지 않습니다.)\n\n## 개선 방향 및 참고 사항\n- **상태 동기화**: `custom_patch.py` 내의 `source_page_patch` 및 `target_page_patch` 함수가 구현되지 않은 상태로 확인됩니다. 향후 페이지 복제 이후 양방향 상태 업데이트 기능 추가가 필요합니다.\n- **필터 검증**: 사용자 정의 필터의 복잡도에 따라 Notion API의 최대 깊이 제한 이슈가 완벽히 대응되는지 추가적인 테스트가 필요할 수 있습니다.\n\n---\n*본 프로젝트는 개인적인 자동화 편의성을 위해 설계되었으며, 비즈니스 요구사항에 맞춰 확장 가능하도록 모듈화되어 있습니다.*",
  "saved_path": "outputs/README.generated.md",
  "section_check": {
    "프로젝트 소개": true,
    "주요 기능": true,
    "프로젝트 구조": true,
    "핵심 파일 설명": false,
    "기술 스택": true,
    "시스템 아키텍처": true,
    "실행 방법": true,
    "기술 선택 이유": true,
    "개선 방향": true
  }
}

readme_markdown은 README.md 파일의 내용이다. saved_path는 README.md 파일이 저장될 위치를 명시한다. section_check는 README.md 파일의 내용이 잘 들어가 있는지 확인하는, hook의 역할을 수행한다.

 

#5-6 [05] Pull Request 전송

# in main.py
...
def main():
    ...
    final_readme = writer_output.get("readme_markdown")
    ...
    publish_result = repo_mgr.publish_readme(TARGET_REPO, final_readme)
...

repo_manager.py 모듈을 호출해 Pull Request를 보낸다. repo_manager.py는 파이프라인의 시작(1단계)과 끝(5단계)에서 각각 쓰였다. publish_result의 예시는 아래와 같다.

 

{
  "status": "success",
  "pr_url": "https://github.com/Kanmanemone/notion-auto-clone/pull/3"
}

참조: 이 프로그램을 통해 실제로 전송된 Pull Request

 

#6 나의 생각

#6-1 General AI Model과의 비교

README.md 작성을 GPT, Claude같은 General AI Model에게 '시키면' 되는 거 아닌가? 이 프로그램의 의의는 존재할까? 존재한다고 본다. 범용 LLM이 '정말 말만 하면 다 해주는' 수준까지 도달하는 미래가 아니라면 말이다. 이렇게 좁은 분야에서라면 충분히 경쟁력이 있다. 나는 아직 맛만 본 게 전부지만, 하네스 엔지니어링의 개념(hook, #5-5)도 들어가 있어 좋았다. 저런 식으로 쓰면 되겠구나 싶었다. 결국 어느 시점부터는, 범용 LLM에 적당한 커스텀 하네스를 씌운 것이 대부분의 프로그램보다 나은 날도 오겠다는 생각도 든다. 개발자로서는 섬뜩하다. 하지만 개발자 이전에 사용자로서 기대도 된다.

 

#6-3 오탈자와 동아리

소스 코드에 (없는 변수를 호출한다든가 하는 식의) 오탈자가 꽤 있어서 직접 고친 후 분석해야 했다. 그래도, 원본 프로그램 자체는 고치지 않아도 잘 돌아가기는 했다. 그리고 이 부분을 내가 "못했다"라고 표현하긴 어렵다. 왜냐하면 절대적 시간이 부족해 보였기 때문이다. 발표자(연사)는 4명으로 이루어진 코딩 동아리였는데, 1학기 중간고사 기간 도중 짬을 내서 만든 것 같았다.

 

많은 사람이 모이는 무대에서 직접 만든 프로그램을 보여주는 게 정말 멋져 보였다. 약간은 부럽기까지 했다. 내가 대학생 때 있었던 동아리는 댄스 동아리였는데, 그게 후회된 적은 한번도 없었다... 그때로 돌아간다면 && 하루가 48시간이라면 춤 동아리에 더해 코딩 동아리까지 가입해야겠다.

 

#6-4 다양한 도메인 지식

#4에 있는 내용을 배울 수 있어서 좋았다. 콘퍼런스가 좋은 점이 이거다. 내가 모르는 걸 아는 사람이, 친절하고 열정적으로 그 내용을 알려준다는 것.