107 lines
6.9 KiB
Markdown
107 lines
6.9 KiB
Markdown
# 연구 협업 및 가이드라인 문서
|
|
|
|
본 문서는 **"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` 저장소 하나만 클론하면 하부 서브모듈까지 일정한 디렉터리 경로로 즉시 연동됩니다:
|
|
```bash
|
|
# 서브모듈을 포함하여 재귀적으로 클론
|
|
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/` 폴더 내에 배치하며, 문서 내에서는 **상대 경로**로 참조합니다:
|
|
```markdown
|
|
|
|
```
|
|
- 절대 경로를 사용하거나 Obsidian 전용 내부 위키 링크(`[[image]]`)를 쓰는 것은 Overleaf 변환 시 문서를 손상시키므로 금지합니다.
|
|
|
|
### 3.2 Overleaf 형식화 및 동기화 절차
|
|
1. **마크다운 초안 완성**: `paper_draft/` 아래의 장별 마크다운 문서 검토를 완료합니다.
|
|
2. **LaTeX 변환**: `pandoc` 컴파일러를 이용해 마크다운 파일을 LaTeX 포맷(`.tex`)으로 변환합니다:
|
|
```bash
|
|
pandoc paper_draft/chapter3_design.md -f markdown -t latex -o build/chapter3_design.tex
|
|
```
|
|
3. **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 |
|