ai-architecture-harness

AI_STUDY

한 문장 정의

AI_STUDY는 사용자가 알고 싶은 AI, 보안, 시스템, 개발 주제를 AI가 조사하고, 초급부터 고급까지 이어지는 교재형 lesson으로 정리해 Notion에 안전하게 누적하는 학습 운영 프로젝트입니다.

무엇을 하는가

이 저장소는 "AI로 공부한다"를 일회성 답변이 아니라 반복 가능한 학습 파이프라인으로 만듭니다. 사용자가 주제를 요청하면 에이전트는 범위를 먼저 고정하고, 최신 자료와 1차 출처를 확인하고, 한 번에 한 page를 충분한 설명 밀도로 작성한 뒤, QA와 Notion 안전 업데이트 절차를 거쳐 학습 지식으로 저장합니다.

핵심 기능은 다음과 같습니다.

• 주제 요청을 Topic Brief로 좁혀 이번 page의 목표와 제외 범위를 정합니다.
• Source Pack으로 출처, 검증일, 최신성 판단을 남깁니다.
• # 초급, # 중급, # 고급 구조로 한 page를 교재처럼 자세히 작성합니다.
• 필요한 경우 짧은 코드 예시와 바로 아래 해설을 포함합니다.
• lesson QA, source pack 검증, topic brief 검증을 로컬 스크립트로 확인합니다.
• Notion에 쓸 때는 중복 page와 잘못된 overwrite를 막는 safe update 절차를 사용합니다.

왜 필요한가

AI에게 학습 주제를 물어보면 빠른 답은 얻을 수 있지만, 시간이 지나면 출처, 구조, 깊이, 이전 학습과의 연결이 흩어지기 쉽습니다. AI_STUDY는 이 문제를 줄이기 위해 학습 결과를 "검증 가능한 한 page" 단위로 쌓습니다.

이 프로젝트의 목표는 단순 요약이 아닙니다. 처음 보는 사람도 큰 그림을 이해하고, 중급자는 실제 흐름을 따라가며, 고급 독자는 내부 원리와 실패 모드까지 확인할 수 있는 설명을 만드는 것입니다.

어떻게 동작하는가

기본 운영 흐름은 다음 순서입니다.

1. 사용자가 학습하고 싶은 주제를 말합니다.
2. 에이전트가 이번 page의 범위, depth, 선행 지식, 코드 필요 여부를 Topic Brief로 잠급니다.
3. 최신성이 필요한 주제는 공식 문서, 논문, 벤더 문서 같은 1차 출처를 우선 확인해 Source Pack을 만듭니다.
4. lesson draft는 현재 위치, 이번 글의 목표, 선행 지식, 핵심 그림, 초급, 중급, 고급, 출처 순서로 작성합니다.
5. lesson-qa-check.py, source-pack-check.py, topic-brief-check.py로 저장 전 품질을 확인합니다.
6. Notion 저장이 필요한 경우 notion-safe-update-check.py로 write plan을 먼저 검증합니다.
7. 저장 후 fetch로 page가 실제로 의도대로 반영됐는지 확인합니다.
8. 활동 로그와 세션 인수인계를 갱신합니다.

결과는 무엇인가

AI_STUDY를 따르면 학습 결과는 다음 상태로 남습니다.

• 한 요청에서 한 page가 충분히 깊게 완성됩니다.
• 초급, 중급, 고급 설명이 같은 흐름으로 이어집니다.
• 출처와 검증일이 남아 stale 정보를 구분할 수 있습니다.
• Notion page 중복과 relation 손상을 줄입니다.
• 다음 세션이 같은 주제의 맥락을 이어받을 수 있습니다.

기능 추가/수정 판단 기준

새 기능을 추가하기 전에 기존 lesson 파이프라인으로 해결 가능한지 먼저 봅니다.

• 새 기능 추가: 반복되는 학습 작업이 있고, 입력/출력/검증 기준을 독립적으로 정의할 수 있을 때.
• 기존 기능 수정: lesson 품질은 맞지만 설명 순서, QA 기준, Notion 업데이트 절차가 부족할 때.
• 보류: 사용자의 학습 목표나 성공 기준이 불명확하거나 검증 방법이 없을 때.
• 축소: 자동화가 설명 품질보다 복잡도를 더 키울 때.

시작 방법

프로젝트 상태 확인:

python scripts/verify-skeleton.py
python scripts/list-open-questions.py --count

lesson 관련 검증:

python scripts/topic-brief-check.py <topic-brief.md>
python scripts/source-pack-check.py <source-pack.md>
python scripts/lesson-qa-check.py <lesson.md>

Notion write plan 검증:

python scripts/notion-safe-update-check.py <plan.json>

구현 연결 정보

• Codex 진입 문서: AGENTS.md
• 프로젝트 프로필: docs/PROJECT_PROFILE.md
• 프로젝트 명세: docs/PROJECT_SPEC.md
• lesson 품질 기준: docs/LESSON_QUALITY_STANDARD.md
• 문서 안내: docs/README.md
• 운영 루프: docs/OPERATING_LOOP.md
• Notion 문서화 규칙: docs/NOTION_DOCUMENTATION_RULES.md
• 검증 템플릿: runtime/validation/
• 활동 로그: runtime/activity-log.jsonl
• 세션 인수인계: runtime/state/session-handoff.md