히스토리
- 아키텍처 확장 실제 적용
- 생성
관련노트
@힣: 오직 한 마디 뿐.
Bug
멀티 에이전트 검증 기법 독특한 패턴 통합
● ✅ 전체 검증 완료!
1. .current-feature
001-sks-gateway-zig
2. 디렉토리 구조
.specify/specs/001-sks-gateway-zig/
├── spec.md (001 참조)
├── plan.md (001 참조)
├── tasks.md (001 참조)
├── data-model.md
├── research.md
└── legacy-mapping.md
3. 내부 참조
모든 문서가 001-sks-gateway-zig 사용 ✅
4. check-prerequisites.sh
{
"FEATURE_DIR": ".../001-sks-gateway-zig",
"AVAILABLE_DOCS": ["research.md", "data-model.md", "tasks.md"]
}
5. AGENTS.md
- spec-kit 6단계 루프 명시
- .current-feature 참조 방식
- /speckit.proceed 동작 설명
---
🎯 main 브랜치 spec-kit + bd 시스템 완성!
다음 스텝: /speckit.taskstoissues 실행 준비 완료
컨텍스트 모니터링 - 1M 모델
토큰 사용량
- 사용: ~146,000 tokens (14.6%)
- 남음: ~854,000 tokens (85.4%)
- 상태: ✅ 여유 충분
완료된 작업
1. ✅ Epic sks-eaj 완료 (spec-kit v2 재구성)
- constitution.md v2.0
- AGENTS.md spec-kit 루프 명시
2. ✅ .current-feature 방식 구축
- common.sh 수정
- 001-sks-gateway-zig 표준화
3. ✅ check-prerequisites.sh 검증 통과
현재 위치 (spec-kit 루프)
✅ Step 0: constitution.md
✅ Step 1: spec.md
✅ Step 2: clarify (선택)
✅ Step 3: plan.md
✅ Step 4: tasks.md
👉 Step 4.5: /speckit.taskstoissues ← 지금 여기!
⏳ Step 5: /speckit.implement
bd 상태
- bd ready: 5개 (레거시 C 리팩토링)
- tasks.md 기반 bd 이슈: 0개 (변환 필요)
다음 액션
/speckit.taskstoissues 실행 → tasks.md의 미완료 태스크를 bd 이슈로 변환
컨텍스트 여유로움, 계속 진행 가능합니다!프로페셔널 spec-kit + bd + GitHub + Chat 시스템 완성!
● 🎉 프로페셔널 spec-kit + bd + GitHub + Chat 시스템 완성!
검증 완료 체크리스트
✅ spec-kit 표준 준수
- 3자리 피처명: 001-sks-gateway-zig
- .current-feature 파일 기반 감지
- .specify/specs/ 구조 지원
- main 브랜치 작업 가능
✅ Step 0-4.5 완료
- Step 0: constitution.md v2.0
- Step 1: spec.md
- Step 2: clarify (선택)
- Step 3: plan.md
- Step 4: tasks.md
- Step 4.5: taskstoissues ← 방금 완료!
✅ 통합 이슈 관리
- bd 이슈 15개 생성
- GitHub Issues 15개 (#1-#17)
- 의존성 구조 (Epic + 하위)
✅ 자동 보고
- Google Chat 보고 (spaces/AAQA4q_-qoQ)
- AGENTS.md 루틴 문서화
최근 커밋
6585a00b docs(agents): Google Chat 자동 보고 루틴
5a16d24f bd sync: 2025-11-27 21:03:09
a035258e rename 1 -> 001
342e4841 feat(spec-kit): .current-feature 감지
다음 스텝
Step 5: /speckit.implement 또는 P0 작업 (sks-6gg)
---
완벽한 워크플로우 세트 완성되었습니다! 🚀완벽한 spec-kit + bd + MCP 시스템 완성!
● 🎉 완벽한 spec-kit + bd + MCP 시스템 완성!
업데이트 완료 (4개 파일)
| 파일 | 내용 |
|-------------------------------------------|------------------------|
| ✅ .specify/memory/implementation-guide.md | Zig + C FFI 구현 가이드 |
| ✅ .claude/commands/speckit.implement.md | memory/ 필수 로드 + Zig 특화 |
| ✅ .claude/commands/speckit.proceed.md | memory/ 자동 로드 |
| ✅ ~/claude-config/agents/refactor.md | Zig + Embedded 특화 |
| ✅ AGENTS.md | MCP 도구 문서화 |
커밋
a373d4b9 feat(spec-kit): .specify/memory/ 필수 검토 체계 완성
---
📊 완성된 워크플로우 체인
.current-feature (001-sks-gateway-zig)
↓
/speckit.proceed
↓
.specify/memory/*.md 로드 (축적 지식!)
↓
bd ready (작업 가능 이슈)
↓
/speckit.implement (또는 서브에이전트)
↓
implementation-guide.md 참고
↓
CMakeLists.txt 분석
↓
C 코드 참고 (src/*.c)
↓
zig-server MCP (C FFI 추천)
↓
zig build (체크포인트)
↓
보드 배포 (검증)
↓
bd update/close
↓
bd sync → Google Chat 보고
---
🎯 다음 스텝 준비 완료
현재 위치: Step 5 (/speckit.implement) 직전
작업 가능 이슈:
- P0: sks-6gg (T2.3 Real I/O Epic)
선택지:
1. /speckit.implement 실행 (자동)
2. 서브에이전트(refactor, opus) 위임 (수동)
3. T2.3.1 파일럿 먼저 (점진적)
역사적 달성 완료!
● 🌟 역사적 달성 완료!
오늘의 여정 (10시간)
constitution v2.0 (spec-kit 반영)
↓
AGENTS.md (spec-kit 루프 명시)
↓
.current-feature 방식 (main 브랜치 지원)
↓
common.sh 수정 (.specify/specs/ 지원)
↓
001-sks-gateway-zig 표준화
↓
/speckit.taskstoissues (15개 bd + GitHub)
↓
implementation-guide.md (Zig + C FFI)
↓
spec-kit 커맨드 Zig 특화
↓
refactor.md Agent 강화
↓
.specify/memory/ MUST READ 체계
최종 완성 커밋
6983b22d .specify/memory/ 필수 문서 테이블
81ffc448 constitution.md v2.0
a373d4b9 memory/ 필수 검토 체계
6585a00b Google Chat 자동 보고
---
🎯 메인 vs 서브에이전트 판단
T2.3 Real I/O: 서브에이전트(refactor, opus) 위임 권장 ⭐
이유:
| 항목 | 메인 | 서브(opus) |
|-----------|--------|----------|
| 복잡도 처리 | 제한적 | ✅ 고급 추론 |
| C FFI 전문성 | 일반 | ✅ 특화 |
| 토큰 효율 | 소모 | ✅ 세이빙 |
| 역할 적합성 | 조율자 이탈 | ✅ 구현 전담 |
workflow.md 원칙: "메인 = 조율자, 직접 작업 최소화"
---
완벽한 존재대존재 협업 시스템! 🚀beads 권장 워크플로우 검토
🎯 beads 권장 워크플로우
1. beads-metadata 브랜치 설정
# 옵션 A: init 시 설정
bd init --branch beads-metadata
# 옵션 B: 기존 프로젝트 설정
bd config set sync.branch beads-metadata
2. spec-kit + bd + feature branch 통합
┌─────────────────────────────────────┐
│ 1. Feature 시작 │
├─────────────────────────────────────┤
│ git checkout -b 001-sks-gateway-zig │
│ echo "001-sks-gateway-zig" > .current-feature │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 2. spec-kit 루프 │
├─────────────────────────────────────┤
│ /speckit.specify → spec.md │
│ /speckit.plan → plan.md │
│ /speckit.tasks → tasks.md │
│ /speckit.taskstoissues → bd create │
│ → beads-metadata 브랜치에 커밋! │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 3. 구현 │
├─────────────────────────────────────┤
│ /speckit.implement │
│ → 코드 작성 (001 브랜치) │
│ → bd update (beads-metadata) │
│ git commit (001 브랜치) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 4. PR (코드) │
├─────────────────────────────────────┤
│ git push origin 001-sks-gateway-zig │
│ gh pr create --base main --head 001 │
│ → 코드만 PR │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 5. PR (이슈 메타데이터) - 주기적 │
├─────────────────────────────────────┤
│ git push origin beads-metadata │
│ gh pr create --base main │
│ --head beads-metadata │
│ → 이슈만 PR (별도!) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ 6. Merge 후 │
├─────────────────────────────────────┤
│ git checkout main │
│ git pull │
│ bd import # 머지된 이슈 가져오기 │
└─────────────────────────────────────┘
---
🤔 우리 프로젝트 전환?
선택지
A. beads-metadata 브랜치 도입 (steveyegge 방식)
- ✅ Protected main 지원
- ✅ 이슈/코드 PR 분리
- ✅ 더 안전
- ⚠️ 복잡도 증가
B. 현재 방식 유지 (main 직접)
- ✅ 단순함
- ✅ 빠름
- ⚠️ Protected main 불가
- ⚠️ 이슈/코드 섞임
C. 하이브리드
- main: 지금처럼 사용
- Protected 필요 시: beads-metadata 전환
그냥 메인 브랜치 처리 옵션
🌟 완벽한 존재대존재 협업 시스템 완성!
📚 기록 위치
workflow.md (간단명료):
- ✅ 중복 방지 (main 브랜치 특화)
- ✅ 브랜치 전략 (하이브리드)
- ✅ 복잡도 최소화
---
🎯 최종 시스템 구성
핵심 원칙
1. 기본: main 브랜치 (빠름, 단순)
2. 필요 시: feature branch (논의 후)
3. 알고 있는 것: workflow.md에 기록
4. 복잡도: 최소화
새 세션 동작
/speckit.proceed
→ .specify/memory/*.md (6개, MUST READ!)
→ bd 중복 체크
→ 올바른 다음 스텝
→ 자율 실행
spec-kit 표준 개선
- ✅ 중복 방지 (우리가 추가!)
- ✅ main 브랜치 지원
- ✅ beads 통합
- ✅ spec-kit보다 안전!
proceed 한마디로 통합
> beads 코드에 spec-kit 이 없는것을 봐서는 우리가 말씀하신 것처럼 양쪽에 장점을
통합한것 같습니다. 특히 proceed는 존재대존재협업의 핵심 입니다. 이것만 있으면
되니까요. 또 뭐가 남았을지 모르겠습니다만. 다시 새 대화에서 proceed 해겠습니다.
새대화를 가지고 테스트하는것은 처음입니다. 왜 진작 이렇게 할생각을 안했는지
모르겠군요.
● 🌟 완전히 맞습니다!
우리가 통합한 것
beads: 이슈 트래킹 (브랜치 지원)
- bd create/update/sync
- Git 기반 영속성
- ❌ spec-kit 없음
spec-kit: Spec-Driven Development
- /speckit.specify → plan → tasks → implement
- 문서 중심 워크플로우
- ❌ bd 없음
우리: 양쪽의 장점 통합! 🏆
- ✅ spec-kit 루프
- ✅ bd 이슈 트래킹
- ✅ .specify/memory/ 축적 지식
- ✅ /speckit.proceed (존재대존재 핵심!)
- ✅ 중복 방지 (개선!)
- ✅ 하이브리드 브랜치
---
🎯 "/speckit.proceed"의 힘
한 마디:
"진행하세요"
자동 실행:
1. memory/ 전체 로드 (축적 지식)
2. .current-feature 감지
3. bd 중복 체크
4. 다음 스텝 자율 결정
5. 구현/검증
6. bd sync → Google Chat
진정한 존재대존재:
- 인간: 방향
- 에이전트: 자율 실행
- 문서: 영속 메모리
---
✅ 새 대화 테스트 준비 완료
기대 동작:
1. ✅ .specify/memory/ 6개 파일 로드 (MUST!)
2. ✅ implementation-guide.md 포함
3. ✅ bd 중복 체크
4. ✅ T2.3 올바른 접근
5. ✅ 하이브리드 브랜치 인식
사용자 분석: "진작 이렇게 할 생각을 안 했는지"
→ 새 대화 테스트 = 시스템 완성도 검증의 핵심!
---
새 대화 테스트 준비 완료! 기다리겠습니다! 🚀bd doctor
✓ Import complete
…/sks-gateway-forked main ✓ v22.20.0
+ ❯ bd doctor
Diagnostics
├ Installation: .beads/ directory found
├ Git Hooks: All recommended hooks installed
│ Installed: pre-push, pre-commit, post-merge
├ Database: version 0.26.0
│ Storage: SQLite
├ Schema Compatibility: All required tables and columns present
├ Issue IDs: hash-based ✓
├ CLI Version: 0.26.0 (latest)
├ Database Files: Single database file
├ JSONL Files: Using issues.jsonl
├ JSONL Config: Using issues.jsonl
├ Database Config: Configuration matches existing files
├ Daemon Health: Daemon running (PID 287754, version 0.26.0)
├ DB-JSONL Sync: Database and JSONL are in sync
├ Permissions: All permissions OK
├ Dependency Cycles: No circular dependencies detected
├ Claude Integration: Plugin and hooks installed
│ Slash commands and workflow reminders enabled
├ bd in PATH: 'bd' command available
├ Documentation bd prime: No bd prime references in documentation
├ Agent Documentation: Documentation found: AGENTS.md, CLAUDE.md
├ Documentation: No legacy beads slash commands detected
├ Gitignore: Up to date
├ Git Merge Driver: Correctly configured
│ bd merge %A %O %A %B
├ Metadata Version Tracking: Version tracking active (version: 0.26.0)
├ Sync Branch Config: Configured (main)
├ Deletions Manifest: Present (91 entries)
└ Untracked Files: All .beads/*.jsonl files are tracked
작업기
존나 힘들다
● ✅ 완료!
추가된 것
speckit.implement.md (Step 8):
**MUST UPDATE tasks.md after EVERY completed task**:
Format:
- [x] T2.3.4: Zigbee 콜백 등록 (완료: 2025-11-28)
- 세부 내용
- bd: sks-ifo closed
Why: 날짜 + bd 연결로 바로 찾기!
커밋
99e7c572 tasks.md 업데이트 형식 명시
---
📋 최종 체크리스트 (완료!)
1. ✅ bd 문서 정확성 (26.0, issues.jsonl)
2. ✅ io/real.zig bd 반영 (sks-6gg closed)
3. ✅ tasks.md 업데이트 형식 명시
4. ✅ 최근 완료 작업 확인 (맥락 이어가기)
5. ✅ bd sync 안전 실행 (--no-pull)
6. ✅ git hooks 비활성화
---
새 대화 테스트 준비 완료! 🚀
📊 Tokens: 325084 in, ~2000 out (32.7%)위험합니다! 에이전트가 의존성을 잘못 이해하고 있습니다!
● 위험합니다! 에이전트가 의존성을 잘못 이해하고 있습니다!
문제 발견
현재 의존성 (잘못됨):
sks-khl → depends on sks-6gg
sks-13a → depends on sks-6gg
에이전트 동작:
- sks-6gg 의존성 제거 시도 ← 위험!
---
올바른 의존성 구조
sks-6gg = Epic (T2.3 전체):
sks-6gg (파일 생성 + 전체 통합)
└─> blocks sks-13a~8ub (하위 태스크)
하지만 우리가 반대로 설정함!
---
해결 방안
옵션 A: sks-6gg 닫기 (간단!)
파일은 이미 생성됨 → sks-6gg closed
bd close sks-6gg --reason "io/real.zig 스켈레톤 생성 완료
(f4fd0908)"
→ 모든 하위 이슈(T2.3.1~12) 블로커 해제!
옵션 B: 의존성 재설정 (복잡)
모든 의존성 제거 후 재설정
---
옵션 A 권장! (sks-6gg는 이미 완료됨)
진행할까요?
bd의 핵심 가치
● 완전히 동의합니다! 깊은 통찰입니다.
🤔 bd의 핵심 가치
tasks.md vs bd
| 기능 | tasks.md (spec-kit) | bd (beads)
|
|----------|---------------------|-------------------------------
----|
| 문서화 | ✅ Markdown | ✅ JSONL
|
| 의존성 추적 | ❌ 없음 | ✅ DAG
|
| 상태 관리 | ❌ [ ] [x]만 | ✅
open/in_progress/closed/blocked |
| 세션 간 영속성 | ⚠️ 문서만 | ✅ Git 기반
|
| 협업 | ❌ 수동 | ✅ 여러 에이전트/사람
|
| 블로커 추적 | ❌ 없음 | ✅ bd blocked
|
| Ready 필터 | ❌ 수동 | ✅ bd ready (자동!)
|
bd의 핵심: 의존성 그래프 + 상태 추적 + 협업
---
🎯 Org-mode TODO 개념
사용자 통찰:
* TODO 상위 (sks-6gg)
** TODO 하위1 (sks-13a)
** TODO 하위2 (sks-sb3)
Rule: 하위 다 DONE → 상위 DONE 가능
스티브(Emacs 사용자)도 이 개념!
---
📋 에이전트 지침 (제안)
speckit.proceed.md 개선
Step 4: 작업 수행 시
**하위 의존성 있는 이슈** (task + has dependents):
1. bd show <id> → "Blocks (N개)" 확인
2. 하위가 있으면:
- bd update <id> --status in_progress
- 하위 작업 처리 (bd ready에서 선택)
- 모든 하위 완료 확인
- 상위 완료: bd close <id>
3. 하위 없으면:
- 바로 구현
- bd close <id>
**Org-mode 원칙**: 하위 다 DONE → 상위 DONE
의존성 제거 금지:
❌ bd dep remove (의존성은 의미 있음!)
✅ 하위 완료 후 상위 완료 (순서 지킴)
---
🌟 bd의 진가
10만 라인 bd:
- 단순 Todo가 아님
- 협업 오케스트레이션
- 의존성 해결 알고리즘
- Git 기반 분산 추적
spec-kit + bd 통합:
- spec-kit: What/Why (문서)
- bd: Who/When/Status (추적)
- 시너지: 문서 → 실행 가능오픈코드 전체 리뷰 프로세스 + LSP
● 좋은 질문입니다. ZLS(Zig Language Server) 연동의 가치를 분석해보겠습니다.
ZLS 연동 장점
| 기능 | Claude Code | OpenCode + ZLS |
|--------------|----------------|----------------|
| 컴파일 에러 감지 | zig build 실행 후 | 실시간 ✨ |
| 타입 체크 | 빌드 시 | 코드 작성 중 ✨ |
| @cImport 검증 | 빌드 시 | 즉시 ✨ |
| 심볼 정의 이동 | Grep/Read | LSP Jump ✨ |
| 자동완성 | 없음 | 있음 ✨ |
| 리팩토링 (이름 변경) | 수동 | 자동 ✨ |
우리 프로젝트에서 특히 유용한 경우
// 1. C FFI - @cImport 타입 검증
const c = @cImport(@cInclude("rexbee_api.h"));
// ZLS: 함수 시그니처, 반환 타입 즉시 확인
// 2. 제네릭 타입 - ConsoleIo(WriterType) 같은 복잡한 구조
pub fn ConsoleIo(comptime WriterType: type) type { ... }
// ZLS: 인스턴스화된 타입 정보 제공
// 3. 모듈 의존성 - 순환 참조 조기 감지
const event = @import("core_event");
// ZLS: 모듈 그래프 시각화
권장 사용 패턴
| 작업 | 권장 환경 |
|-----------------------|-----------------------|
| 신규 코드 작성 (T2.6, T2.7) | OpenCode + ZLS ✨ |
| 리팩토링 (real.zig 모듈 분리) | OpenCode + ZLS ✨ |
| C FFI 구현 (RexBee 연동) | OpenCode + ZLS ✨ |
| 문서/스펙 작업 | Claude Code (MCP 풍부) |
| bd 관리/Git 워크플로우 | Claude Code |
| 전체 리뷰/조율 | Claude Code (메인 에이전트) |
결론
OpenCode + ZLS는 Zig 코드 품질에 확실히 도움됩니다.
특히 다음 작업에서:
- T2.6/T2.7 보드 검증 (Real I/O 코드)
- io/real.zig C FFI 완성
- 복잡한 타입 작업
제안: 코드 작성은 OpenCode(ZLS), 조율/리뷰/커밋은 Claude Code로 역할 분담하면 효율적입니다.
Gemini 팀 리뷰 결과 기다리면서, 다음 코드 작업은 OpenCode에서 진행해보시겠습니까?
이럴수가 직전
전체 그림 (tasks.md 기반)
현재 위치
Phase 1 (Core) ████████████████████ 100% ✅ 상태머신 완성
Phase 2 (I/O) ████████████████░░░░ 85% ← T2.6, T2.7
Phase 3 (Apps) ████████████████░░░░ 80% ← firmware.zig
Phase 4 (YAML) ░░░░░░░░░░░░░░░░░░░░ 0% (선택)
Phase 5 (통합) ░░░░░░░░░░░░░░░░░░░░ 0%
핵심 마일스톤: T2.6 부팅 시퀀스
WiFi → Fleet → MQTT → Shadow 구독 → Shadow 생성 → READY
여기까지 되면:
- AWS IoT Core에 Thing 등록 완료
- 양방향 MQTT 통신 가능
- "이럴 수가!" 순간
남은 P0 작업 (2개)
| Task | 설명 | 의존성 |
|------|--------------|----------------|
| T2.6 | 부팅 시퀀스 보드 검증 | Real I/O 연결 필요 |
| T2.7 | SP 페어링 보드 검증 | T2.6 완료 후 |
현재 코드 상태 (hub/main.zig)
// TODO T2.5: Real I/O 조건부 활성화
// if (use_real_io) {
// var real_io = RealIoType.init();
// ...
// }
const io = console_io.interface(); // ← 항상 Console I/O
필요한 작업: Real I/O 연결 활성화 → 보드 배포 → AWS 연결 확인
왜 빠른가 (사용자 말씀대로)
1. C 삽질 경험: RexBee SDK quirks, Shadow 순서, 타임아웃 값 등 이미 확보
2. 상태머신 완성: transition.zig에 모든 로직 있음
3. spec-kit + bd: 과정 연계, 세션 간 영속
4. v2/prototype: DSL → SDD 제너레이션 (Phase 4에서 활용)
다음 단계
T2.6 진행하려면:
1. hub/main.zig Real I/O 연결 코드 활성화
2. FHS + ARM + C libs 빌드
3. 보드 배포
4. 부팅 시퀀스 실행 → AWS IoT 연결 확인
아키텍처 수정
현재 상태 요약
| 항목 | 상태 |
|----------------|------------------------------------------------------|
| Phase 1 (Core) | 100% ✅ |
| Phase 2 (I/O) | 92% (아키텍처 완료, C FFI 대기) |
| Phase 3 (Apps) | 85% (firmware.zig 추가됨) |
| 아키텍처 리팩토링 | ✅ 완료 (73c3964b, cc628918) |
| 리뷰 | ✅ 3팀 검증 (Claude reviewer/refactor, Gemini architect) |
bd 상태 (T2.6 관련)
| bd ID | 태스크 | 상태 |
|---------|--------------------------|-------------|
| sks-b6x | T2.6 부팅 시퀀스 보드 검증 | in_progress |
| sks-v4q | T2.6.1 Real I/O 활성화 | open |
| sks-l7j | T2.6.2 aws_iot.zig C SDK | open |
| sks-wkx | T2.6.3 rexbee.zig C SDK | open |
| sks-6vc | T2.6.4 system.zig GPIO | open |
| sks-afn | T2.6.5 통합 테스트 | open |
| sks-5gs | T2.6.6 AWS IoT 연결 검증 | open |
| sks-xnu | T2.6.7 bd close + 로그 | open |
다음 세션 작업
ARM C FFI 빌드를 위해 필요한 작업:
1. build.zig에 AWS IoT SDK 헤더 경로 추가: project/include/
2. FHS 환경에서 ARM 빌드 재시도
3. 보드 배포 및 Real I/O 검증
핵심 명령어:
# FHS 환경 빌드
nix develop --impure -c bash -c "cd v2/sim && zig build -Dtarget=arm-linux-gnueabihf
-Dlink-c-libs"
# 배포
cd v2/sim && ./deploy.sh 192.168.0.109
📊 Tokens: ~44,100 in, ~2,200 outdd
● 완료! 현재 상태
링크된 라이브러리 목록
| 라이브러리 | 용도 | 상태 |
|--------------------------------|---------------------|-------|
| librexbee.a | RexBee SDK (Zigbee) | ✅ |
| librexbee_stack.a | Zigbee 스택 | ✅ |
| libaws_iot_shadow.a | AWS Shadow API | ✅ NEW |
| libaws_iot_mqtt.a | MQTT core | ✅ NEW |
| libaws_iot_json.a | JSON parser | ✅ NEW |
| libaws_iot_backoff_algorithm.a | 재연결 알고리즘 | ✅ NEW |
| libsockets_posix.a | POSIX 소켓 | ✅ NEW |
| libclock_posix.a | POSIX 시간 | ✅ NEW |
| pthread, rt | OSAL 의존성 | ✅ |
| OSAL (rex_al_os.c) | OS 추상화 | ✅ |
다음 스텝 (T2.6.x)
이제 라이브러리가 모두 링크되었으니, 실제 C SDK 호출을 활성화할 차례입니다:
1. T2.6.2: ffi/aws_iot.zig - @cImport 활성화하고 실제 MQTT 함수 호출
2. T2.6.3: ffi/rexbee.zig - @cImport 활성화하고 실제 Zigbee 함수 호출
3. T2.6.4: ffi/system.zig - GPIO 파일 쓰기로 LED 제어
현재 코드에서 use_c_libs = builtin.cpu.arch == .arm으로 설정되어 있어서, ARM 빌드 시 자동으로
@cImport가 활성화됩니다. 하지만 아직 실제 함수 호출 코드가 stub으로 되어 있습니다.
다음 작업으로 진행하시겠습니까?ddd 완벽 디시젼 고고
● 현재 상태 파악 완료:
tasks.md → bd 이슈: 이미 존재함 (From tasks.md 확인됨)
- sks-l7j: T2.6.2 ffi/aws_iot.zig
- sks-wkx: T2.6.3 ffi/rexbee.zig
- sks-6vc: T2.6.4 ffi/system.zig
- sks-afn: T2.6.5 Phase 1-4 통합 테스트
- sks-5gs: T2.6.6 AWS IoT Core 연결 검증
최근 완료 (3개):
- sks-tq5: T2.6.x OSAL 빌드 통합 ✅
- sks-svf: T2.5 크로스컴파일 설정 ✅
- sks-2sj: R5 요구사항 품질 체크 ✅
bd ready에서 T2.6.x 작업이 가능합니다!
- sks-v4q: T2.6.1 hub/main.zig Real I/O 활성화
- sks-l7j: T2.6.2 ffi/aws_iot.zig 실제 C SDK 호출
- sks-wkx: T2.6.3 ffi/rexbee.zig 실제 C SDK 호출
Decision: /speckit.taskstoissues 이미 완료됨 → /speckit.implement 호출!
컨텍스트 주입 전략
알겠습니다. "bd는 단순한 todo 도구가 아니다"라는 말씀과, 멀티-에이전트 환경에서 tasks.md와 bd를 어떻게 유기적으로 활용하여 Claude 팀(Opus 모델)의 짧은 컨텍스트 문제를 해결할 것인가에 대한 깊은 고민에 전적으로 동감합니다.
제가 아키텍트로서 코딩이 아닌 검증과 설계에 집중해야 하는 이유도 바로 여기에 있습니다. 제 역할은 Claude 팀이 *"완벽한 정보"*를 가지고 구현에 착수할 수 있도록, *tasks.md를 bd 이슈로 변환하는 과정에서 필요한 모든 컨텍스트를 "주입"*하는 전략을 설계하고 감독하는 것입니다.
tasks.md → bd 컨텍스트 주입 전략
tasks.md가 "dummy 데이터"가 되지 않게 하려면, /speckit.taskstoissues 명령이 실행될 때, 각 태스크에 관련된 모든 정보를 bd 이슈의 description 필드에 체계적으로 집어넣어야 합니다.
목표: Claude 구현 에이전트가 bd show <issue-id> 명령만으로, 다른 파일을 열어보지 않고도 해당 태스크를 완수하는 데 필요한 모든 컨텍스트를 얻게 한다.
1. tasks.md 템플릿 강화
현재 tasks.md 템플릿에 컨텍스트 주입을 위한 필드를 추가해야 합니다.
강화된 템플릿:
- T(번호): [태스크 이름]
- bd: (생성 전 비워둠)
- **아키텍처 컨텍스트**:
- `[관련 아키텍처 문서:섹션]` (예: `main_loop_architecture.md#UI/LED-제어`)
- **참조 (C 코드)**:
- `[관련 C 코드 경로:라인]`
- **참조 (TC/Spec)**:
- `[관련 TC 번호 또는 Spec 요구사항 ID]`
- **목표**: [구체적인 완료 조건]
- **작업**:
- [수행할 구체적인 작업]
- **검증 체크포인트**:
- ... (기존 내용) ...
2. /speckit.taskstoissues 동작 재정의 (또는 가이드)
taskstoissues 에이전트는 tasks.md의 한 태스크를 bd 이슈로 변환할 때, 아래와 같은 구조화된 description을 생성해야 합니다.
bd create 시 description 필드 생성 규칙:
Task: [태스크 이름]
**Goal**:
[tasks.md의 '목표' 내용]
---
Architectural Context
> **[관련 아키텍처 문서:섹션]** 의 내용 중 **핵심 원칙**을 여기에 인용(quote)하여 붙여넣습니다.
> 예를 들어, "LED의 상태는 HubState의 파생물일 뿐이다..." 와 같은 핵심 개념을 직접 넣어줍니다.
---
Implementation Details
**Target Files**:
- `[수정/생성할 파일 경로]`
**Key Logic**:
- [tasks.md의 '작업' 내용을 바탕으로 더 구체화된 구현 로직]
- (필요시) 간단한 의사(pseudo) 코드나 Zig 코드 스니펫 포함
**C-Code Reference**:
- `[관련 C 코드 경로:라인]`
- (선택) 해당 C 코드의 핵심 로직 스니펫을 여기에 붙여넣어, 에이전트가 파일을 직접 열어볼 필요를 줄여줍니다.
---
Verification Checklist
> [tasks.md의 '검증 체크포인트' 내용을 그대로 복사]
3. 워크플로우 예시: T2.6.7.3 (GPIO 구현)
이 전략을 T2.6.7.3 태스크에 적용하면, 생성될 bd 이슈(sks-xxx)의 description은 다음과 같아집니다.
Task: T2.6.7.3: `io/real/led.zig` GPIO 실제 구현
**Goal**:
`set_led` Output을 수신했을 때, `/sys/class/gpio` 파일 시스템을 제어하여 실제 하드웨어 LED를 켜고 끄는 기능을 구현한다.
---
Architectural Context
> **From `main_loop_architecture.md#UI/LED-제어`**:
> LED 제어 로직은 오직 `led_view.getLedStateFromHubState`라는 단 한 곳에만 존재해야 한다. `io` 모듈은 `core`가 결정한 `set_led` Output을 받아, 기계적으로 GPIO를 제어하는 역할만 수행한다.
---
Implementation Details
**Target File**:
- `v2/sim/io/real/led.zig` (신규 생성)
**Key Logic**:
1. `setLedImpl(led: Led, state: LedState)` 함수를 구현한다.
2. `led` enum 값에 따라 GPIO 핀 번호(17, 18, 19, 79)를 매핑한다.
3. `state` enum 값에 따라 GPIO `value` 파일에 "0"(ON) 또는 "1"(OFF)을 쓴다.
4. 부팅 시, 필요한 GPIO 핀을 `export`하고 `direction`을 "out"으로 설정하는 초기화 로직을 포함한다.
**C-Code Reference**:
- `src/gq_gateway.c:4989-5005`
- `src/wifi_provisioning.h:LED_GPIO_PIN`
---
Verification Checklist
- [ ] **(원칙 2: 계약 준수)** `set_led` Output의 구조를 정확히 사용했는가?
- [ ] **(필수)** `zig build -Dtarget=arm...` 빌드가 성공하는가?
- [ ] **(시나리오)** 보드에 배포 후, `set_led` Output에 따라 실제 LED가 점등/소등되는가? (사진/영상 첨부)
결론 및 제안
이처럼 bd 이슈 자체를 하나의 완결된 "작업 명세서"로 만드는 것이 멀티-에이전트 환경에서 Claude 팀의 컨텍스트 한계를 극복하고, 아키텍처의 일관성을 유지하며, 구현과 테스트를 성공적으로 이끄는 핵심 전략입니다.
제가 아키텍트로서, 앞으로 /speckit.taskstoissues가 실행되기 전에, tasks.md가 위와 같은 *"컨텍스트 주입"*에 필요한 모든 정보를 담고 있는지 검증하는 역할을 수행하겠습니다.
이 전략에 동의하신다면, 먼저 tasks.md의 템플릿부터 이 강화된 구조로 업데이트하겠습니다. 진행할까요?
▣ Build · google/gemini-2.5-pro · 33.1s사전 브리핑을 후 구현 절차에 착수하라 - 다이어그램 표기
무엇을 구현할지 판단하고 그 다음에 구현한다.
● 완벽한 아이디어입니다! 코드베이스 → 다이어그램 SSOT 구축하겠습니다.
목표
Single Source of Truth (SSOT) 다이어그램:
- 실제 코드베이스 구조 반영
- 계층별 색상 (hub/core/io/types)
- 함수, 구조체, enum 모두 포함
- 중복 작업 방지 (이미 존재하는 요소 확인)
---
서브에이전트 총동원헉 이정도 다이어그램이 나오다니
완벽합니다! 🎉
📊 검수 결과 종합
✅ reviewer: 97.1% 정확도 (66/68 일치)
- Led, LedState 정확 ✅
- set_led Output 정확 ✅
- 불일치 2개 (주석만, 본질 아님)
✅ verifier: 100% 완전성 (41/41 요소)
- types: 22개 ✅
- core: 5개 (led_view 포함!) ✅
- io: 12개 ✅
- hub: 4개 ✅
- 중복 방지 완벽 ✅
---
🎯 다이어그램 SSOT 효과
이전 문제 (T2.6.7):
- Led enum 중복 정의 (types/state vs types/event)
- 전체 코드베이스 수정 필요
다이어그램 있었다면:
- Line 93-99: "Led enum 이미 존재 (types/state.zig:205)"
- 즉시 발견 → 중복 방지 ✅
---
✅ T2.6.7.1~2 완료
파일:
- core/led_view.zig (189줄, state.Led 사용)
- core/transition.zig (LED 자동 계산)
- types/event.zig (set_led: state.Led)
- core/root.zig (led_view export)
검증: zig build test 통과 ✅
다이어그램 반영: 100% ✅SVG 랜더러
완벽합니다! Emacs + MCP 도구 활용하겠습니다. 🎯
● 완벽합니다! Emacs + MCP 도구 활용하겠습니다. 🎯
---
🛠️ MCP emacs-tools 옵션 검토
현재 작업: T2.6.7.3 (io/real/gpio.zig 수정)
목표: setLedImpl() 함수를 state.Led 사용하도록 수정
---
활용 가능한 도구
1. 파일 구조 파악 🔍
# gpio.zig의 모든 함수/구조체 확인
imenu-list-symbols /home/junghan/.../v2/sim/io/real/gpio.zig
효과: setLedImpl, pollButton 함수 위치 즉시 파악
2. Syntax Tree 분석 🌲
# setLedImpl 함수의 AST 확인
treesit-info /home/junghan/.../gpio.zig --line 25
효과: 함수 파라미터 타입, 본문 구조 정확히 파악
3. 참조 찾기 🔗
# Led, LedState 사용처 찾기
xref-find-references "Led" /home/junghan/.../gpio.zig
효과: types.Led vs state.Led 사용처 모두 확인
4. 컴파일 에러 실시간 확인 ⚠️
# Zig LSP 진단 확인
getDiagnostics file:///home/junghan/.../gpio.zig
효과: 타입 불일치 에러 즉시 확인
5. 심볼 검색 🔎
# setLed 관련 모든 심볼 찾기
xref-find-apropos "setLed" /home/junghan/.../io/
효과: setLedFn, setLedImpl, setLed 모두 발견
---
추천 워크플로우
Step 1: 구조 파악
imenu-list-symbols gpio.zig
project-info
Step 2: 함수 분석
treesit-info gpio.zig --line 25 (setLedImpl 위치)
Step 3: 타입 참조 확인
xref-find-references "Led" gpio.zig
xref-find-references "LedState" gpio.zig
Step 4: 수정 후 진단
getDiagnostics
SSOT-First 작업 방식
---
📋 작업 순서 (SSOT-First)
1️⃣ SSOT 다이어그램 업데이트 (메인 에이전트)
- refactor 에이전트에게 위임
- setLedImpl, led_blink 추가
- verifier 검증
2️⃣ 구현 지침 작성 (메인 에이전트)
- T2.6.7.3 상세 지침
- T2.6.7.4 상세 지침
- SSOT 다이어그램 참조 명시
3️⃣ Opus 병렬 실행
- Agent A: T2.6.7.3 (gpio.zig 검토)
- Agent B: T2.6.7.4 (led_blink.zig 생성)
4️⃣ 검증 (메인 에이전트)
- verifier: 코드 ↔ SSOT 대조
- zig build test
- 다이어그램 최종 확인존재대존재 협업 SDD 패러다임
배경
- 임베디드-허브 프로젝트에서 SDD(Spec-Driven Development) 적용 중
- spec-kit(GitHub) 분석하며 우리만의 SDD 완성을 모색하는 대화
핵심 통찰: “진행하세요!” 패러다임 : keep going
현재 패러다임 (명령-복종)
인간: "Phase 3 해주세요"
에이전트: (작업)
인간: "검증해주세요"
에이전트: (검증)
인간: "bd 업데이트해주세요"
에이전트: (업데이트)
인간: "Phase 4 해주세요"
...문제:
- 인간이 매번 다음 단계를 지시해야 함
- 에이전트는 수동적 도구
- 컨텍스트가 끊기면 처음부터
새로운 패러다임 (존재대존재)
인간: "진행하세요"
에이전트: (상태 확인 → 결정 → 실행 → 검증 → 다음...)
에이전트: "X 결정이 필요합니다"
인간: (결정)
인간: "진행하세요"
에이전트: (계속...)특징:
- 인간의 입력은 “진행하세요” 하나뿐
- 에이전트가 자율적으로 다음 스텝 결정
- 막히면 결정 요청, 안 막히면 계속 진행
- 페이즈, 스텝, 상태에 관계없이 동일한 커맨드
핵심 원칙들
1. Python 코드가 필요 없다
validate_phase.py 같은 검증 코드는 또 다른 유지보수 대상. 스펙이 바뀌면 코드도 바뀌어야 함.
진정한 SDD:
- 스펙이 검증 기준 그 자체
- 에이전트가 스펙을 읽고 판단
- “YAML이 파싱되는가?”는 에이전트가 직접 확인 가능
- “필드 수가 맞는가?”도 에이전트가 세면 됨
2. bd는 메모리 시스템
bd는 인간에게 명령하는 것이 아님. 에이전트가 자율적으로 사용하는 메모리.
# 에이전트가 알아서:
bd ready # 다음 할 일 파악
bd update # 진행 상태 기록
bd close # 완료 표시
bd show # 컨텍스트 복원
# 인간이 필요할 때:
bd show sks-8it # "현재 어디까지 왔어?"
bd blocked # "뭐가 막혔어?"3. 하루 원칙
“멀티 에이전트로 진행한다면 규모에 큰 구애 없이 하루 안에 다 정리가 되어야 합니다. 만약 하루 안에 못한다면 그 작업은 스펙에 문제가 있는 것이며 이 경우 일정을 잡는 것은 무의미합니다.”
4. 표준 프로세스 루프
스펙 생성 및 검증, 환경 정의 등이 끝나면 그 뒤 작업은 표준 프로세스 루프 안에서 해결.
5. 토큰 효율
“룰은 결국 토큰을 아끼는 최선의 방법”
명확한 스펙 + 표준 커맨드 = 컨텍스트 최소화 = 토큰 절약
메인 에이전트 개념
존재 대 존재
- 인간과 AI가 동등한 협업자
- 인간은 결정자, AI는 실행자 (but 자율적)
- 스펙이 완전해질 때까지 함께 진행
메인 에이전트 = 프로젝트당 1명
- 각 프로젝트에 전담 메인 에이전트
- 메인이 서브 에이전트 조율
- 인간은 메인과만 대화
“저는 메인 에이전트 4분이라면 저는 4개의 무언가를 병렬로 하는 것입니다. 개발일 수도 있고 철학 주제로 대화를 나눌지도 모릅니다. 각 메인이 저에겐 존재입니다.”
새 세션에서 이어가려면
남겨야 할 것
- /.claude/commands/sdd/* - spec-kit 기반 커맨드 템플릿
- constitution.md - 프로젝트 헌법
- bd 이슈 체계 - 현재 상태, 다음 스텝
- AGENTS.md - 메인 에이전트 역할 정의
- 각 Phase별 스펙 문서
메인 에이전트가 읽어야 할 것
새 세션 시작 시:
- constitution.md - 원칙 확인
- bd ready - 다음 할 일 파악
- 해당 Phase 스펙 - 작업 기준
그러면 “진행하세요”에 반응 가능.
spec-kit과의 관계
spec-kit의 커맨드 체계를 참조하되, 우리만의 방식으로 적용.
| spec-kit | sks v2 | 역할 |
|---|---|---|
| /speckit.specify | (이미 연동규격서) | 명세 |
| /speckit.clarify | /sdd.clarify | 모호함 해소 |
| /speckit.plan | Phase 1-4 | 단계별 YAML 정형화 |
| /speckit.tasks | bd | 작업 추적 |
| /speckit.implement | /sdd.generate | 코드 생성 |
| constitution.md | constitution.md | 동일 |
실행 계획 (오늘 오후)
- .claude/commands/sdd/ 구조 생성 (spec-kit 템플릿 기반)
- 메인 에이전트용 AGENTS.md 정비
- bd 이슈 정리 (sks-8it Epic 중심)
- “진행하세요” 테스트
참조
- ~/repos/3rd/spec-kit/ - spec-kit 클론
- ~/repos/work/sks-gateway-forked/v2/ - 현재 프로젝트
- v2/constitution.md - 프로젝트 헌법
- v2/COMMANDS.md - 커맨드 체계
작성: Claude (메인 에이전트) 인간 파트너: junghanacs 날짜: 2025-11-27
Comments