7.1 KiB

Raw Permalink Blame History

AI 협업 기본 규칙

이 문서는 이 프로젝트에 참여하는 모든 AI와 사람이 공통으로 따라야 할 기본 규칙입니다.

프로젝트의 방향이 흔들리지 않도록, 새로 참여하는 AI는 작업을 시작하기 전에 반드시 이 문서를 먼저 읽어야 합니다.

프로젝트 요약

이 프로젝트는 Orange Pi Zero 2W를 마이크 송신기로 사용하고, Mac을 수신기이자 믹서로 사용하는 Wi-Fi 오디오 시스템입니다.

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/ 폴더에 자신의 작업 플랜을 기록합니다.

플랜 파일은 작업 요청마다 새로 만들지 않습니다. 하나의 대화 또는 스레드에서는 plans/{uuid}.md 파일 1개만 사용합니다.

기본 절차:

현재 대화에서 이미 사용 중인 plans/{uuid}.md가 있는지 먼저 확인합니다.
기존 플랜 파일이 있으면 새 요청도 반드시 그 파일에 이어서 기록합니다.
기존 플랜 파일이 없을 때만 대화를 식별할 임시 고유 UUID를 생성하고 plans/{uuid}.md 파일을 생성합니다.
해당 파일에 현재 요청의 할 일 목록을 작성합니다.
작업을 순차적으로 진행하면서 같은 .md 파일의 할 일 상태와 메모를 수정합니다.
작업 완료 후 결과 요약을 같은 파일에 남깁니다.

새로운 사용자 요청이 같은 대화 안에서 이어질 경우에는 같은 플랜 파일 안에 ## 추가 요청 - {YYYY-MM-DD HH:mm} 같은 새 섹션을 추가합니다. 새 UUID와 새 .md 파일을 만들지 않습니다.

플랜 파일은 작업의 흐름을 남기기 위한 기록입니다. 사용자가 실행을 지시하지 않은 코드 구현을 정당화하는 용도로 사용하지 않습니다.

권장 형식은 plans/README.md를 따릅니다.

설계 원칙

초기 목표는 복잡한 기능보다 안정적인 오디오 경로 확인입니다.

우선순위:

Orange Pi에서 USB 라발리에 마이크 인식
Mac에서 UDP 수신 가능 여부 확인
단일 송신기 오디오 전송 검증
지연 시간과 끊김 확인
다중 송신기 믹싱
압축, 동기화, 자동 검색, UI 같은 확장 기능 검토

초기 설계에서 지나치게 복잡한 기능을 먼저 넣지 않습니다.

OS 이미지 규칙

os/ 폴더에는 Orange Pi OS 이미지 파일을 보관할 수 있습니다.

다운로드한 원본 압축 파일인 .7z는 커밋할 수 있습니다. 단, 압축을 풀어서 나온 실제 디스크 이미지 파일은 용량이 크고 Git에 적합하지 않으므로 커밋하지 않습니다.

커밋하지 않는 파일 예시:

os/*.img
os/*.img.*
os/*/*.img
os/*/*.img.*

일반 ARM64 Debian/Ubuntu 이미지가 아니라 Orange Pi Zero 2W 전용 이미지를 사용해야 합니다.

외부 정보 확인

OS 다운로드 링크, 보드 지원 상태, 라이브러리 지원 여부처럼 시간이 지나며 바뀔 수 있는 정보는 가능한 최신 공식 자료를 확인합니다.

우선순위:

Orange Pi 공식 문서
라이브러리 공식 문서
운영체제 공식 문서
커뮤니티 자료

커뮤니티 자료를 사용할 경우 공식 자료가 아니라는 점을 명확히 표시합니다.

문서 수정 규칙

문서를 수정할 때는 다음 기준을 지킵니다.

한국어로 자연스럽게 작성합니다.
실제로 결정된 내용과 후보를 구분합니다.
추측은 결정처럼 쓰지 않습니다.
명령어는 검증된 경우에만 절차로 적습니다.
아직 구현되지 않은 기능을 이미 있는 기능처럼 설명하지 않습니다.

금지 사항

다음 작업은 하지 않습니다.

사용자 승인 없는 코드 생성
사용자 승인 없는 대규모 구조 변경
Python 기반 구현 추가
압축 해제된 .img OS 이미지 파일 커밋
보드 전용 이미지가 아닌 일반 ARM64 이미지를 권장
확인되지 않은 성능 수치를 확정값처럼 작성
사용자가 만든 변경사항 되돌리기

새 AI를 위한 첫 행동

새로 참여한 AI는 다음 순서로 시작합니다.

README.md를 읽습니다.
docs/00-ai-collaboration-rules.md를 읽습니다.
현재 Git 변경사항을 확인합니다.
사용자의 최신 요청을 확인합니다.
현재 대화에서 이미 사용 중인 plans/{uuid}.md가 있는지 확인합니다.
기존 플랜 파일이 있으면 그 파일만 수정하고, 없을 때만 새 UUID 파일을 만듭니다.
코드가 필요한 작업이면 먼저 계획을 제시합니다.
사용자가 실행을 지시하기 전까지 구현하지 않습니다.

7.1 KiB Raw Permalink Blame History