Codaro가 하나의 문서 모델을 쓰는 이유

Codaro에서 사용자는 Python을 배우고, 셀을 실행하고, 그 코드를 반복 업무 자동화로 키운다. 이 흐름이 끊기지 않으려면 에디터, 커리큘럼, 자동화가 서로 다른 자료 구조가 아니라 같은 파일과 셀 구조를 공유해야 한다.

Codaro가 만들고 싶은 것은 기능을 많이 붙인 노트북이 아니다. 배운 코드가 실행 가능한 코드가 되고, 실행한 코드가 검증된 뒤 dry-run을 거친 자동화 후보가 되는 흐름이다.

화면은 달라도 흐름은 하나다

Codaro의 제품 표면은 채팅, 에디터, 커리큘럼, 자동화로 나뉜다.

• 채팅에서는 목표를 말한다.
• 커리큘럼에서는 학습 셀을 읽고 실행한다.
• 에디터에서는 Python 셀과 Markdown 셀을 직접 고친다.
• 자동화에서는 검증한 셀과 스크립트를 반복 실행 후보로 모은다.

이 네 화면이 서로 다른 저장 형식을 쓰면 사용자는 같은 내용을 계속 옮겨야 한다. 학습에서 쓴 코드를 자동화로 가져가려면 복사, 수정, 재검증이 반복된다.

Codaro는 이 단절을 줄이기 위해 같은 문서 모델을 제품 계약으로 맞추고 있다. 현재 학습 문서의 물리 타입은 markdown과 code를 중심으로 두고, 자동화 작성 경계에서는 automation block도 사용한다. 셀의 의미는 역할, 화면 표현, 실행 종류, 원본 payload 같은 metadata로 설명한다. 장기적으로는 code, text, guide, widget, view, file 같은 block 중심 모델로 확장할 수 있게 둔다.

커리큘럼도 실행되는 문서다

Codaro 커리큘럼은 읽기 전용 글이 아니다. curricula/의 YAML은 학습 셀 카드로 전개되고, 사용자는 그 안에서 예측하고, 실행하고, 오류를 고치고, 검증한다.

좋은 레슨은 설명으로 끝나지 않는다.

1. 먼저 결과를 예측한다.
2. 로컬 Python 셀을 실행한다.
3. 실패하면 오류를 읽고 고친다.
4. assert나 출력 비교로 검증한다.
5. 값을 바꿔 실무 변주를 만든다.

그래서 커리큘럼 셀은 에디터와 떨어진 별도 콘텐츠가 아니라, 같은 실행 흐름에 올라오는 문서 조각이어야 한다. 외부 패키지가 필요한 레슨도 마찬가지다. 필요한 패키지는 레슨의 meta.packages에 선언하고, 실행 전에는 packages-check로 확인한 뒤 누락된 경우에만 packages-install을 거쳐 cell-call로 실행한다.

자동화는 검증된 셀에서 시작한다

반복 업무 자동화도 같은 이유로 별도 세계가 되면 안 된다.

Codaro의 자동화 작성 기준은 커리큘럼 YAML에 모든 것을 억지로 넣는 방식이 아니다. 검증한 Python 셀과 percent-format recipe를 바탕으로 automation 셀을 만들고, dry-run 결과를 확인한 뒤 task 등록 후보로 다룬다.

예를 들어 공개 데모의 흐름은 작다.

uv run python -X utf8 demos/publicLaunch/expenseSummaryDemo.py
uv run python -X utf8 demos/publicLaunch/fileOrganizerDemo.py

첫 번째 데모는 CSV를 읽어 요약 결과를 만든다. 두 번째 데모는 실제 파일을 옮기지 않고 dry-run 정리 계획을 보여준다. 이 데모들은 완성된 자동화 플랫폼의 과시가 아니라, Codaro가 자동화를 다루는 최소 기준을 보여준다. 실행 결과를 먼저 확인하고, 파일 이동 같은 변경 작업은 dry-run 검토 뒤에만 다음 단계로 보낸다.

local-first가 모델을 단순하게 만든다

Codaro는 로컬 Python 실행을 기본으로 둔다. 학습자가 셀을 실행하고, 결과를 보고, 파일과 패키지를 자기 환경 안에서 확인할 수 있어야 한다.

이 기준은 문서 모델에도 영향을 준다. 셀은 화면 장식이 아니라 실행 단위다. .py percent format은 # %% 경계로 셀을 나누면서도 파일 자체가 Python으로 실행될 수 있게 만든다. 그래서 같은 문서는 에디터에서는 노트북이고, 커리큘럼에서는 학습 단위이며, 자동화에서는 태스크 원본 후보가 될 수 있다.

지금 글에서 약속하는 것

이 글은 Codaro가 완성된 자동화 플랫폼이라고 말하려는 글이 아니다. 지금 공개적으로 말할 수 있는 것은 제품이 따르는 계약과 경계다.

• Codaro는 채팅, 에디터, 커리큘럼, 자동화를 하나의 흐름으로 설계한다.
• 학습 YAML은 실행 가능한 셀 문서로 전개되는 방향을 가진다.
• 자동화는 검증 없는 즉시 실행보다 dry-run과 태스크 등록 경계를 우선한다.
• 공개 사이트와 문서는 이 판단을 검색 가능한 기록으로 남긴다.

Codaro의 차별점은 기능 수가 아니라 연속성이다. 학습 셀에서 시작한 코드가 실행 결과로 확인되고, dry-run을 거쳐 task 후보가 되는 흐름을 만들고 있다. 하나의 문서 모델은 그 흐름을 끊지 않기 위한 제품 구조다.