위키독스 분석 보드 — 2026-06-28

스프링부트로 게시판 하나를 끝까지 만들어보며 자바 웹 개발의 '코끼리 전체'를 보여주는 실습형 입문서 — 프레임워크가 제공하는 구조·자동화·보안을 직접 코딩하며 체득하게 한다.

스프링부트 입문서라 Java/Python 언어 갭이 커서 직접 코드 이식 가치는 낮지만, '프레임워크가 강제하는 구조 규율'과 '선언적 라우팅'이라는 두 메타 패턴은 형님 시스템에 실질적 개선 포인트를 준다. adopt 1개(핫 리로드), improve 4개(디렉터리 규율, dev/prod 분리, 선언적 라우팅, 아키텍처 문서화), skip 3개 — 핵심 가치는 '구조를 도구가 강제하게 하라'는 프레임워크 설계 철학.

1. IMPROVE 프로젝트 디렉터리 구조 규율 (src/main/java, resources, templates, static 분리)
   agent_registry.py에 등록 시 디렉터리 위치 검증 로직 추가 (예: pipeline agent는 pipelines/, domain agent는 domains/<domain>/). skill-creator 스킬의 SKILL.md 템플릿에 '반드시 이 디렉터리에 생성할 것' 규칙 명시. PreToolUse 또는 PostToolUse hook에서 새 파일 생성 시 디렉터리 규칙 위반을 경고.
2. IMPROVE 개발 전용 vs 운영 전용 의존성 분리 (developmentOnly, runtimeOnly)
   pyproject.toml 또는 requirements-dev.txt 분리. pyproject.toml에 [project.optional-dependencies] 섹션으로 dev/test/lint 구분. harness_integration.run_as_automation에서 운영 배포 시 dev 의존성 제외 로직 추가. pip-audit 스캔 대상을 운영 의존성으로 한정.
3. ADOPT 핫 리로드 자동화 (Spring Boot Devtools — 서버 재시작 없이 코드 변경 반영)
   watchdog(파일 변경 감시 라이브러리)를 사용한 `dev_reloader.py` 작성. skills/ 또는 agents/ 디렉터리 변경 시 자동으로 해당 모듈의 selftest를 실행하고 결과를 터미널에 출력. developmentOnly 개념을 차용해 프로덕션 launchd plist에는 포함되지 않도록 분리.
4. IMPROVE @Controller / @GetMapping 애너테이션 기반 URL 라우팅
   Python decorator 기반 `@route("keyword")` 패턴 도입. 각 에이전트 파일 상단에 `@agent_route(["키워드1", "키워드2"])` 데코레이터를 붙이면 agent_registry.py가 import 시 자동 수집하도록 변경. decorator를 단 파일 자체가 자신의 라우팅을 선언하므로 registry를 열어보지 않아도 된다.
5. IMPROVE 시스템 전체를 보는 '코끼리' 교육 철학 — 부분 아닌 전체 이해
   ARCHITECTURE.md 작성. HARNESS_DOMAIN_REGISTRY.md를 확장해 agent 간 데이터 흐름도, 주요 파이프라인 시퀀스 다이어그램(Mermaid), '하루 동안 어떤 에이전트가 어떤 순서로 실행되는지'를 한 장에 보여주는 오케스트레이션 맵 포함. system-dashboard 스킬에 이 ARCHITECTURE.md를 참조하도록 연결.

파이썬 웹 프레임워크 플라스크로 Q&A 게시판(파이보)을 0에서 완성까지 실습하며 웹 개발의 '코끼리 전체'를 보여주는 입문서 — 앱 팩토리·블루프린트·ORM·마이그레이션 등 구조적 패턴을 단계별로 체득시킨다.

Flask 입문서로서는 훌륭하지만 우리 시스템(CLI 자동화·130+ agent)에 직접 전이되는 패턴은 제한적 — 제공된 29% 범위에서 adopt 3건(db 마이그레이션 체계·사전지식 명시 문화·auto-reload), improve 2건(팩토리 패턴 응용·ORM 추상화), skip 3건(Blueprint·가상환경 진입·DB Browser). 핵심 가치는 '웹 프레임워크의 구조적 설계 패턴을 CLI 자동화 도메인으로 전이하는 메타 사고'에 있고, Flask 문법 자체에는 거의 없음. 전체 62챕터 중 나머지 44챕터(사용자 인증·페이징·배포 등)도 비슷한 비율로 건질 게 있을 것 — 남은 분량 크롤링 분석 후 최종 판단 권장.

1. ADOPT 데이터베이스 마이그레이션 체계 (Flask-Migrate)
   프로젝트 루트에 `db_migrations/` 디렉터리 생성. SQLite 전용 경량 마이그레이션 헬퍼 `db_migrate.py` 작성: (1) `versions/` 폴더에 YYYYMMDD_HHMMSS_desc.sql 파일 (2) `schema_version` 테이블로 적용 이력 추적 (3) `python db_migrate.py upgrade`로 미적용 마이그레이션 순차 실행. Flask-Migrate를 그대로 가져오는 게 아니라 패턴만 추출.
2. IMPROVE 애플리케이션 팩토리 패턴 (create_app)
   `harness_integration.py`에 `get_agent(name)` 지연 로더 함수 추가. agent 간 직접 import 대신 `from harness_integration import get_agent`를 사용하도록 컨벤션 정립. `pre_write_harness_check.py` (PostToolUse hook)에 순환참조 감지 검사 추가.
3. IMPROVE ORM 기반 데이터 계층 추상화 (SQLAlchemy)
   `/db/models.py` 생성, SQLAlchemy Core(ORM 아님)로 기존 SQLite 테이블을 반영한 Table 정의 작성. `obsidian_keywords` 시스템의 키워드 CRUD를 raw SQL → SQLAlchemy Core로 리팩토링. 우선순위: Channel Bridge DB → 키워드 DB 순.
4. ADOPT 환경변수를 통한 실행 모드 전환 (FLASK_DEBUG)
   개발용 `agent_watchdog.py` 작성: `watchdog` 라이브러리로 agents/ 디렉터리 감시 → .py 파일 변경 시 해당 agent 자동 재실행(개발모드 플래그 있을 때만). `hermes agent dev <name> --watch` 명령으로 실행. 기존 PostToolUse hook과 충돌 없도록 --dev 모드에서만 발동.
5. ADOPT 프로젝트 사전 지식 명시 + 버전 명시 문화 (0-03 이 책을 읽기 전에)
   SKILL.md 템플릿에 `prerequisites:` YAML 필드 추가 (Python 버전·필요 라이브러리·선행 SKILL/agent). `pre_write_harness_check.py` hook에 SKILL.md 생성/수정 시 prerequisites 필드 검증 추가. agent_registry.py 각 엔트리에 `python_min_version` 필드 추가.