통전 장비를 다루는 소프트웨어다. 일반 웹 개발과 다른 점 셋 — 계약을 먼저 고정하고, 실기에 올리기 전에 세 번 거르고, 사람이 마지막에 선다. 나머지는 평범하게 한다.
토픽·페이로드·API 를 코드보다 먼저 정하고 스키마로 박는다. 그래야 양쪽이 동시에 개발된다.
단위 → 시뮬레이터 → 실기. 🔴 실기가 첫 시험장이 되면 안 된다.
배포·통전·리포트 발행은 사람이 누른다. 자동화는 그 앞까지다.
"왜 이렇게 했나"가 코드에 안 남는다. A 시리즈가 그 자리다 — 바꿀 때도 문서를 먼저 고친다.
보드·미니PC·포털·AI 서버 넷이 서로를 기다리면 아무것도 안 된다. 계약을 먼저 박고 목(mock)으로 붙여 넷이 동시에 간다.
| 계약 | 어디에 | 바꿀 때 |
|---|---|---|
| MQTT 토픽·페이로드 | A13 → JSON Schema | 🔴 버전을 올린다. 조용히 필드를 바꾸지 않는다 |
| 포털 ↔ AI 서버 API | 스키마 파일 | 구 버전을 한동안 함께 받는다 |
| 도구 정의 | 스키마 + 설명 | 도구를 늘리는 것은 안전, 인자를 바꾸는 것은 위험 |
| 배포 패키지 형식 | 서명 · 매니페스트 | 구형 장비가 못 읽으면 업그레이드 자체가 막힌다 |
①배터리 없이 — 통신·시퀀스·화면만 확인. ②더미 로드 — 전류가 실제로 흐르는지. ③실제 셀 — 여기서 처음으로 사고가 가능해진다. 순서를 바꾸지 않는다.
그리고 용량 스케일이 미확정인 채로 ③에 가지 않는다 — 값이 10배 어긋나면 보호 한계가 무의미해진다.
이미 쓰고 있고, 계속 쓴다. 다만 어디까지 맡기는지를 정해 둔다 — 정해 두지 않으면 급할 때 위험한 것까지 맡기게 된다.
| # | 규칙 |
|---|---|
| 1 | 🔴 실기에 직접 붙어 파일을 고치지 않는다. 사본에서 고치고 패키지로 올린다 (A05 §04) |
| 2 | AI 가 만든 것도 사람 이름으로 커밋한다. 책임이 흐려지지 않게 |
| 3 | 붙여 넣기 전에 왜 이렇게 되는지 설명할 수 있어야 한다. 못 하면 아직 넘길 때가 아니다 |
| 4 | 🔴 SSH · 부팅 · 파티션을 건드리는 작업은 AI 에게 맡기지 않는다 — 복구 경로다 |
| 5 | AI 세션 로그를 남긴다. 나중에 A08 자립 단계의 학습 자산이 된다 |
구성 요소가 따로 올라간다. 보드만 올리고 앱을 안 올리면 계약이 어긋난다.
| 구성 요소 | 올라가는 주기 | 호환 규칙 |
|---|---|---|
cycler_main · 보드 펌웨어 | 드묾 | 🔴 가장 보수적으로. 검증 자산이다 |
| 보드 웹 · 단위작업 실행기 | 보통 | 계약 버전을 함께 표기 |
| 미니PC 앱 · 웹 번들 | 잦음 | 구 계약을 한동안 함께 지원 |
| 포털 · AI 서버 | 가장 잦음 | 클라우드라 언제든. 단 구 장비를 버리지 않는다 |
"어느 조합이 함께 도는가"를 배포 화면에서 보여 준다. 현장 14대의 버전이 제각각이 되는 것은 정상이고, 그것을 알고 있는 것이 관리다.
| 항목 | 방식 |
|---|---|
| 문서 | A 시리즈(결정·구조) · B 시리즈(화면) · W(서버). 🔴 결정이 바뀌면 문서를 먼저 고친다 |
| 표기 | 🔴 = 임의 변경 금지 · ⚠ = 되돌리기 어려움 · 표시 없음 = 확정 |
| 미결 관리 | 각 문서 끝 「정해지지 않은 것」. 답이 오면 그 자리에서 지운다 |
| 착수 조건 | 실측이 필요한 항목은 🔴 로 표시하고, 추정으로 진행하지 않는다 |
| 진행 단위 | 화면 1개 · 도구 1개처럼 끝이 보이는 덩어리로 자른다 |
| 완료 기준 | 단위 시험 통과 + 시뮬레이터에서 시나리오 완주 + 문서 갱신 |
설계 문서가 미확인 실측 위에 서 있다 — 보드 node 미기동 원인, 실기 mosquitto 유무, 용량 스케일. 이 셋이 미확인인 채로 구현이 쌓이면 틀린 전제 위의 코드가 된다. 0단계 착수와 병행해서 실측을 끝낸다.
근거 — A05 §01·§04(사람이 하던 네 가지 · 릴리스 파이프라인) · A07 §05(원격 업그레이드) ·
A13(계약과 멱등) · A12 §01(SSH 복구 경로) · A11 §04(node 미기동 미상) · A01 §4.2(용량 스케일)
관련 — A08 종합 · A03 · A04 · A05 · A06 · A07