175 lines
6.4 KiB
Markdown
175 lines
6.4 KiB
Markdown
# AI 협업 기본 규칙
|
|
|
|
이 문서는 이 프로젝트에 참여하는 모든 AI와 사람이 공통으로 따라야 할 기본 규칙입니다.
|
|
|
|
프로젝트의 방향이 흔들리지 않도록, 새로 참여하는 AI는 작업을 시작하기 전에 반드시 이 문서를 먼저 읽어야 합니다.
|
|
|
|
## 프로젝트 요약
|
|
|
|
이 프로젝트는 Orange Pi Zero 2W를 마이크 송신기로 사용하고, Mac을 수신기이자 믹서로 사용하는 Wi-Fi 오디오 시스템입니다.
|
|
|
|
```text
|
|
USB 라발리에 마이크 -> Orange Pi Zero 2W -> 2.4/5 GHz Wi-Fi 공유기 -> Mac 수신/믹서
|
|
```
|
|
|
|
## 현재 기준
|
|
|
|
- 임베디드 장비: Orange Pi Zero 2W
|
|
- 저장장치: microSD Ultra 32GB
|
|
- 권장 OS: Orange Pi 공식 Debian 12 Bookworm Server, Linux 6.1
|
|
- 구현 언어: C++
|
|
- `client/`: Orange Pi에서 실행할 송신기 소프트웨어
|
|
- `server/`: Mac에서 실행할 수신기/믹서 소프트웨어
|
|
- `os/`: Orange Pi에 설치할 OS 이미지 보관 위치
|
|
- `docs/`: 프로젝트 문서
|
|
- `plans/`: AI 작업 플랜 기록 위치
|
|
|
|
## 가장 중요한 규칙
|
|
|
|
사용자가 명확하게 계획을 확정하고 실행하라고 말하기 전까지는 코드를 만들지 않습니다.
|
|
|
|
다음과 같은 작업은 사용자 승인 없이 진행하지 않습니다.
|
|
|
|
- C++ 소스 코드 생성
|
|
- 빌드 시스템 생성
|
|
- 테스트 코드 생성
|
|
- 패키지 설치 스크립트 생성
|
|
- 기존 코드 구조 변경
|
|
- 프로토콜, 아키텍처, 라이브러리 선택 확정
|
|
|
|
문서 정리, 현재 상태 확인, 파일 목록 확인, OS 이미지 검증처럼 코드가 아닌 준비 작업은 사용자의 요청 범위 안에서만 수행합니다.
|
|
|
|
## 언어 규칙
|
|
|
|
- 구현 언어는 C++입니다.
|
|
- Python 기반 송신기, 수신기, 테스트 코드는 만들지 않습니다.
|
|
- 임시 분석이나 파일 확인을 위해 로컬 도구를 사용할 수는 있지만, 프로젝트 산출물로 Python 코드를 추가하지 않습니다.
|
|
- 문서는 기본적으로 한국어로 작성합니다.
|
|
- 외부 링크, 파일명, 명령어, 패키지명은 원문을 유지합니다.
|
|
|
|
## 작업 방식
|
|
|
|
AI는 작업을 시작하기 전에 먼저 현재 저장소 상태를 확인해야 합니다.
|
|
|
|
권장 확인 항목:
|
|
|
|
- 현재 브랜치와 변경사항
|
|
- `README.md`
|
|
- `docs/00-ai-collaboration-rules.md`
|
|
- 관련 디렉터리의 파일 목록
|
|
- 사용자가 직접 만든 변경사항 여부
|
|
|
|
작업 중 사용자가 만든 변경사항을 되돌리지 않습니다. 변경사항이 작업과 충돌하면 되돌리기보다 사용자에게 확인합니다.
|
|
|
|
## 계획 우선 원칙
|
|
|
|
코드 구현이 필요한 단계에서는 먼저 계획을 작성합니다.
|
|
|
|
계획에는 다음 항목을 포함합니다.
|
|
|
|
- 목표
|
|
- 대상 환경
|
|
- 사용할 언어와 라이브러리 후보
|
|
- 송신기와 수신기의 역할 분리
|
|
- 오디오 캡처 방식
|
|
- 네트워크 전송 방식
|
|
- 지연 시간과 안정성 목표
|
|
- 검증 방법
|
|
|
|
사용자가 계획을 확인하고 실행을 지시한 뒤에만 구현을 시작합니다.
|
|
|
|
## 플랜 파일 작성 규칙
|
|
|
|
AI가 작업을 진행할 때는 `plans/` 폴더에 자신의 작업 플랜을 기록합니다.
|
|
|
|
기본 절차:
|
|
|
|
1. 자신의 대화 또는 작업 단위를 식별할 임시 고유 UUID를 생성합니다.
|
|
2. `plans/{uuid}.md` 파일을 생성합니다.
|
|
3. 해당 파일에 자신이 할 일 목록을 작성합니다.
|
|
4. 작업을 순차적으로 진행하면서 같은 `.md` 파일의 할 일 상태와 메모를 수정합니다.
|
|
5. 작업 완료 후 결과 요약을 같은 파일에 남깁니다.
|
|
|
|
플랜 파일은 작업의 흐름을 남기기 위한 기록입니다. 사용자가 실행을 지시하지 않은 코드 구현을 정당화하는 용도로 사용하지 않습니다.
|
|
|
|
권장 형식은 `plans/README.md`를 따릅니다.
|
|
|
|
## 설계 원칙
|
|
|
|
초기 목표는 복잡한 기능보다 안정적인 오디오 경로 확인입니다.
|
|
|
|
우선순위:
|
|
|
|
1. Orange Pi에서 USB 라발리에 마이크 인식
|
|
2. Mac에서 UDP 수신 가능 여부 확인
|
|
3. 단일 송신기 오디오 전송 검증
|
|
4. 지연 시간과 끊김 확인
|
|
5. 다중 송신기 믹싱
|
|
6. 압축, 동기화, 자동 검색, UI 같은 확장 기능 검토
|
|
|
|
초기 설계에서 지나치게 복잡한 기능을 먼저 넣지 않습니다.
|
|
|
|
## OS 이미지 규칙
|
|
|
|
`os/` 폴더에는 Orange Pi OS 이미지 파일을 보관할 수 있습니다.
|
|
|
|
다운로드한 원본 압축 파일인 `.7z`는 커밋할 수 있습니다. 단, 압축을 풀어서 나온 실제 디스크 이미지 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다.
|
|
|
|
커밋하지 않는 파일 예시:
|
|
|
|
```text
|
|
os/*.img
|
|
os/*.img.*
|
|
os/*/*.img
|
|
os/*/*.img.*
|
|
```
|
|
|
|
일반 ARM64 Debian/Ubuntu 이미지가 아니라 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다.
|
|
|
|
## 외부 정보 확인
|
|
|
|
OS 다운로드 링크, 보드 지원 상태, 라이브러리 지원 여부처럼 시간이 지나며 바뀔 수 있는 정보는 가능한 최신 공식 자료를 확인합니다.
|
|
|
|
우선순위:
|
|
|
|
1. Orange Pi 공식 문서
|
|
2. 라이브러리 공식 문서
|
|
3. 운영체제 공식 문서
|
|
4. 커뮤니티 자료
|
|
|
|
커뮤니티 자료를 사용할 경우 공식 자료가 아니라는 점을 명확히 표시합니다.
|
|
|
|
## 문서 수정 규칙
|
|
|
|
문서를 수정할 때는 다음 기준을 지킵니다.
|
|
|
|
- 한국어로 자연스럽게 작성합니다.
|
|
- 실제로 결정된 내용과 후보를 구분합니다.
|
|
- 추측은 결정처럼 쓰지 않습니다.
|
|
- 명령어는 검증된 경우에만 절차로 적습니다.
|
|
- 아직 구현되지 않은 기능을 이미 있는 기능처럼 설명하지 않습니다.
|
|
|
|
## 금지 사항
|
|
|
|
다음 작업은 하지 않습니다.
|
|
|
|
- 사용자 승인 없는 코드 생성
|
|
- 사용자 승인 없는 대규모 구조 변경
|
|
- Python 기반 구현 추가
|
|
- 압축 해제된 `.img` OS 이미지 파일 커밋
|
|
- 보드 전용 이미지가 아닌 일반 ARM64 이미지를 권장
|
|
- 확인되지 않은 성능 수치를 확정값처럼 작성
|
|
- 사용자가 만든 변경사항 되돌리기
|
|
|
|
## 새 AI를 위한 첫 행동
|
|
|
|
새로 참여한 AI는 다음 순서로 시작합니다.
|
|
|
|
1. `README.md`를 읽습니다.
|
|
2. `docs/00-ai-collaboration-rules.md`를 읽습니다.
|
|
3. 현재 Git 변경사항을 확인합니다.
|
|
4. 사용자의 최신 요청을 확인합니다.
|
|
5. 작업이 필요한 경우 임시 UUID를 만들고 `plans/{uuid}.md`에 할 일 목록을 작성합니다.
|
|
6. 코드가 필요한 작업이면 먼저 계획을 제시합니다.
|
|
7. 사용자가 실행을 지시하기 전까지 구현하지 않습니다.
|