연구 협업 및 가이드라인 문서

본 문서는 "GAIA (gRPC-based Agent Interface module for AIoT)" 연구 논문 작성 및 모듈 구현을 진행하는 3인 연구팀(환웅, 광선, 사용자)의 GitHub 협업 규칙, Mattermost 연동 방식, Obsidian 초안 ↔ Overleaf 형식화 파이프라인, 그리고 논문 기술 시 지켜야 할 학술 용어 가이드라인을 정의합니다.

1. GitHub 협업 및 브랜치 전략

원활한 코드 개발과 논문 초안 작성을 위해 저장소를 성격에 따라 분리하고, 부모-자식 간의 Git Submodule 연동 구조를 채택합니다.

1.1 저장소 구조 (GAIA Ecosystem)

본 프로젝트는 관심사 격리 및 마크다운 링크 유지 관리를 위해 아래의 3개 저장소 분리 및 서브모듈 구조를 따릅니다.

gaia-paper (Parent 저장소)
- 역할: 메인 논문 초안 마크다운, LaTeX 파일, 피규어 이미지 및 참조 문서 관리.
- 동작: 로컬 상대 경로 링크 유지를 위해 아래 두 저장소를 Submodule로 포함합니다.
gaia-interface (Submodule 1)
- 역할: Go 기반 T2 게이트웨이, Python T1 에이전트 어댑터, .proto 스키마 및 실제 구현 모듈 코드.
gaia-samples (Submodule 2)
- 역할: quic-go 샌드박스, gRPC 기본 스트리밍 예제, MQTT 및 CoAP 프로토타이핑 등 학습 전용 샘플 코드.

로컬 클론 및 초기화 방법

연구원은 gaia-paper 저장소 하나만 클론하면 하부 서브모듈까지 일정한 디렉터리 경로로 즉시 연동됩니다:

# 서브모듈을 포함하여 재귀적으로 클론
git clone --recursive https://github.com/your-org/gaia-paper.git

# 이미 클론받은 경우 서브모듈 초기화 및 업데이트
git submodule update --init --recursive

1.2 브랜치 구조 및 명명 규칙

각 저장소의 핵심 개발 브랜치는 다음과 같이 운영됩니다:

main: 최종 릴리즈 및 제출용 빌드가 동작하는 프로덕션 브랜치.
paper/draft: gaia-paper 저장소에서 논문 마크다운 초안을 공동 편집하는 브랜치.
feature/gate-go: gaia-interface 내에서 Go 기반 T2 게이트웨이 및 quic-go 커스텀 어댑터를 작업하는 브랜치. (환웅 담당)
feature/agent-py: gaia-interface 내에서 Python 기반 T1 에이전트 및 A2A 바인딩을 작업하는 브랜치. (광선 담당)

1.3 Pull Request (PR) 및 코드 리뷰 규칙

모든 코드 및 문서 수정 사항은 개발 브랜치에서 작업 후 paper/draft 또는 main으로 PR을 생성하여 병합해야 합니다.
최소 승인 조건: PR 병합을 위해서는 담당자 외에 **최소 1명 이상의 팀원으로부터의 사전 승인(Approve)**이 필수적입니다.
리뷰 피드백: 단순 반려(NOT PASS)는 금지되며, 반려 시에는 반드시 구체적인 버그/논리적 오류 원인과 대안 코드를 함께 제시해야 합니다.

2. Mattermost 메신저 연동 가이드

팀 내에서 진행 상황을 실시간으로 감지하고 투명하게 공유하기 위해 Mattermost 연동을 다음과 같이 활성화합니다.

2.1 GitHub Webhook 연동

GitHub 저장소 설정(Settings) ➡️ Webhooks ➡️ Add Webhook
Payload URL: Mattermost GitHub Integration 서비스가 제공하는 URL 또는 수신용 웹훅 주소 입력.
Content type: application/json
Events: Pull Requests, Pushes, Issue Comments 활성화.
수신 채널 #git-alert로 실시간 커밋 및 토론 흐름이 공유됩니다.

2.2 테스트베드 알림 연동

에뮬레이션 테스트베드 가동 및 벤치마크 실험 완료 시 실행 결과 데이터가 Mattermost 특정 채널(#experiment-results)로 전송되도록 API 알림 봇 연동 스크립트를 빌드 프로세스에 포함합니다.

3. Obsidian (초안) ➡️ Overleaf (포맷팅) 워크플로우

논문 작성 시 마크다운의 유연함과 LaTeX의 정교한 타이포그래피를 결합하여 작성 효율성을 최대화합니다.

3.1 Obsidian 작성 규칙

모든 초안은 프로젝트 내 paper_draft/ 디렉토리에 마크다운 형식으로 분할 작성합니다.
이미지 및 미디어 파일: assets/images/ 폴더 내에 배치하며, 문서 내에서는 상대 경로로 참조합니다:
```
![아키텍처 구조도](../assets/images/architecture_v1.png)
```
절대 경로를 사용하거나 Obsidian 전용 내부 위키 링크([[image]])를 쓰는 것은 Overleaf 변환 시 문서를 손상시키므로 금지합니다.

3.2 Overleaf 형식화 및 동기화 절차

마크다운 초안 완성: paper_draft/ 아래의 장별 마크다운 문서 검토를 완료합니다.
LaTeX 변환: pandoc 컴파일러를 이용해 마크다운 파일을 LaTeX 포맷(.tex)으로 변환합니다:
```
pandoc paper_draft/chapter3_design.md -f markdown -t latex -o build/chapter3_design.tex
```
Overleaf 업로드:
- Overleaf 프로젝트 내에 생성된 .tex 파일과 이미지 에셋(assets/images/)을 복사/업로드합니다.
- Overleaf Git 연동(Pro 계정)이 활성화되어 있다면, main 브랜치에 변환된 .tex 파일을 직접 푸시하여 원격 컴파일할 수 있습니다.

4. 학술 용어 및 서술 일관성 통일 지침

논문 작성 및 설계 문서화 시, 구어체나 비형식적인 묘사를 배제하고 엄격한 학술 용어를 일관되게 사용합니다.

4.1 핵심 계층 정의

센싱 계층 (Sensing Layer):
- 단순히 데이터를 실시간 업로드하는 것에 그치지 않고, "온도·습도 등의 물리 센서 값을 정량적으로 측정 및 필터링하여 Edge 게이트웨이 또는 Cloud 서비스로 고속 전송"하는 구조적 계층으로 명확히 정의합니다.
제어 계층 (Control Layer):
- 에이전트의 판단에 따라 물리 환경에 개입하는 행위 계층입니다. "농약 살포, 밸브 개폐 등 물리 액추에이터에 직접 명령을 전달하고, 해당 동작이 정상 완료되었는지 루프백(Loopback) 검증하는 계층"으로 정의합니다.

4.2 용어 통일 표

논문 전반에 걸쳐 아래의 용어로 번역 및 표현을 통일합니다:

지양할 표현 (구어체/혼용)	권장할 학술 용어	영문 표기
값을 나르는 레이어, 전달층	센싱 계층	Sensing Layer
일 시키고 확인하는 층, 명령층	제어 계층	Control Layer
엣지박스, 중간 서버	엣지 게이트웨이	Edge Gateway
중복 작동 방지 키, 의도 키	제어 의도 식별자	Control Intent Key
똑같은 결과 보장	멱등성 보장	Idempotency Assurance
끊겼을 때 다시 잇기	단절 내성 / 단절 복구	Disconnection Tolerance / Resilience

6.9 KiB Raw Blame History