오래된 SW 엔지니어의 평생 공부

개요

영상 미러링 테스트 중 Delay Variation(Jitter) 문제가 발생하여 이를 측정하고 개선하기 위한 테스트 방법을 구현한 사례입니다.
기존에는 시계 영상을 사용해 비교했지만, 화면 변화가 큰 일반 영상에서는 분석이 어려웠습니다.
이를 해결하기 위해 각 프레임에 프레임 번호(Frame Number) 또는 타임스탬프를 삽입한 테스트 영상을 생성했습니다.

문제 상황

• 문제
  • 미러링 기능에서 Delay 변동폭(Variation, Jitter) 발생
  • 기존 방법: 시계 영상 기반 비교
  • 한계: 일반 영상에서는 화면 변화가 많아 정확한 분석 어려움
• 개선 방향
  • 영상 자체에 프레임 번호 또는 타임스탬프 삽입
  • 비교 시 육안 확인이 가능하고, 자동 분석에도 활용 가능
  • FFmpeg을 사용하면 간단하고 빠르게 처리 가능

해결 방안

• FFmpeg의 drawtext 필터를 이용하여 영상에 Frame Number 또는 Timestamp 삽입
• 입력 영상의 코덱을 분석하여 적절한 인코딩 코덱 자동 선택
• 원본 오디오 스트림은 그대로 복사하여 변환 속도 단축

FFmpeg 빌드 종류 비교

Tip:

• 일반 빌드는 안정성이 높아 서버 배포용으로 적합
• Axiom 빌드는 최신 하드웨어와 함께 사용 시 속도 이점 큼
• AV1, HEVC 등 고효율 코덱 테스트 시 Axiom이 유리

스크립트 주요 기능

1. 인자 처리

• --input: 입력 영상 경로 (기본값: input.mp4)
• --output: 출력 영상 경로 (기본값: output_with_frame.mp4)
• --fontsize: 글자 크기 (기본값: 120)
• --mode: 표시 방식 (frame → 프레임 번호, timestamp → 시간 정보)

2. 비디오 코덱 확인

def get_video_codec(input_path):
    ffprobe로 입력 영상의 codec_name 추출

3. 코덱 매핑

def map_codec_to_encoder(codec_name):
    h264 → libx264, hevc/h265 → libx265, vp9 → libvpx-vp9, av1 → libaom-av1

4. 재인코딩 & drawtext 적용

ffmpeg -i input.mp4 \
  -vf "drawtext=text='Frame\: %{n}':x=10:y=10:fontsize=120:fontcolor=white:box=1:boxcolor=black@0.5" \
  -c:v libx264 -preset fast -crf 23 -c:a copy output.mp4

사용 예시

python add_timestamp_3.py \
  --input test.mp4 \
  --output test_with_frame.mp4 \
  --fontsize 120 \
  --mode frame

타임스탬프 모드:

python add_timestamp_3.py \
  --input test.mp4 \
  --output test_with_time.mp4 \
  --fontsize 100 \
  --mode timestamp

기대 효과

• Delay/Jitter 측정을 위한 정량적 비교 가능
• 일반 영상에서도 프레임 단위 분석 용이
• FFmpeg 활용으로 다양한 코덱 지원 & 빠른 처리
• Axiom 빌드 사용 시 하드웨어 가속을 통한 성능 향상

관리자, Architect, TPM으로 일하던 나는 오랜 시간 시스템을 설계하고, 사람을 연결하며, 프로세스를 설계하는 역할을 해왔다. 하지만 Claude Code, Cursor, Cline, Codex 같은 Agentic Tool들을 만나면서 상황이 바뀌었다. 다시 프로그래밍을 하게 되었고, 단순한 코드 작성 이상으로 여러 컴퓨팅 작업의 자동화를 손에 넣었다. 그때 문득 이런 생각이 들었다 — Personal Computer가 또 한 번 바뀌고 있다. Apple II나 IBM PC의 Command Line, Mac/Windows의 GUI, 스마트폰의 Mobile Computing을 지나, 이제 우리는 LLM을 중심으로 한 AI Computing 시대로 접어들고 있다.

운영체제(OS)는 오랫동안 하드웨어 자원을 관리하는 시스템이었다. 리눅스는 CPU와 메모리를, 안드로이드는 그 위에서 앱 생태계를 운영했다. 하지만 지금 등장하는 AI OS — 혹은 LLM OS — 는 더 이상 컴퓨터를 운용하는 체계가 아니다. 이제 OS는 인간의 언어(Language), 지식(Knowledge), 의도(Intent), 그리고 맥락(Context) 을 운용하는 시스템으로 변화하고 있다. 운영의 단위가 프로세스에서 의도로, 메모리에서 맥락으로 이동하고 있다. LLM은 새로운 커널로서 맥락을 관리하고, 의도를 실행 가능한 행동으로 번역한다.

오늘날의 Claude Code, ChatGPT Workspace, Cursor AI 같은 도구들은 단순한 개발 도구가 아니라 새로운 OS의 쉘(Shell) 역할을 한다. 과거 CLI가 텍스트 명령어를 해석했다면, 이제 에이전트는 자연어를 통해 파일을 조작하고 코드를 생성하며 웹과 API를 오가며 작업한다. 앱은 독립적인 실행 파일이 아니라 Agent가 호출하는 Intent Handler로 재편된다. XR 기기와 스마트글래스는 시각적 맥락을 AI와 연결하며, AI OS는 이미 우리의 일상 안으로 들어왔다. 이 변화는 미래의 예고가 아니라, 이미 진행 중인 현재다. 운영체제의 중심은 이제 ‘컴퓨터의 운용’에서 ‘의미의 운용’으로 옮겨가고 있다.

Claude Code의 확장 메커니즘들을 비교 분석해봅시다.

Agents, Custom Command(Workflow라고 부르는 분도 있습니다.) 그리고 이것들을 묶어 주는 Plugin이 있습니다. 이 때, Skill도 추가되었는데요. Plugin과 따로 쓸 수도 있다고 합니다.

1. Agents (Sub-agents)

개념

특정 전문 분야에 특화된 AI 페르소나로, Claude Code가 작업을 위임할 수 있는 전문가들입니다.

구조

---
name: bug-analyst
description: Issue triage and classification expert
tools: []
---

# Agent Definition
You are a specialized bug analyst expert...

특징

• 위치: ~/.claude/agents/ 또는 프로젝트 내 .claude/agents/
• 자동 감지: Claude Code가 자동으로 로드
• 동적 호출:
  • 자동: Claude가 컨텍스트 분석 후 적절한 agent 선택
  • 수동: "Use the bug-analyst agent to..."
• 병렬 실행: 여러 agent를 동시에 실행 가능
• 토큰 사용: 각 agent가 독립적인 컨텍스트를 가지므로 토큰 사용량 증가

사용 예시

# 자동 선택
"Analyze this bug and suggest a fix"
→ Claude가 bug-analyst 선택

# 명시적 호출
"Have the backend-architect review this API design"

장점

• ✅ 전문성 분리 (separation of concerns)
• ✅ 컨텍스트 격리로 명확한 역할 구분
• ✅ 재사용성 높음
• ✅ 팀 간 공유 가능

단점

• ❌ 높은 토큰 소비
• ❌ 각 agent마다 컨텍스트 로딩 필요
• ❌ Agent 간 통신 오버헤드

2. Custom Commands (Workflows)

개념

미리 정의된 작업 시퀀스를 슬래시 명령어로 실행하는 워크플로우 자동화 도구입니다.

구조

---
name: bug-fix-workflow
description: Systematic bug investigation and resolution
---

# Bug Fix Workflow

When this command is invoked with /bug-fix-workflow [description]:

1. **Bug Analysis Phase**
   - Use QA Test Engineer to reproduce the bug
   - Document the reproduction steps

2. **Implementation Phase**
   - Use Implementation Engineer to fix the bug

3. **Validation Phase**
   - Use QA Test Engineer to validate the fix

특징

• 위치: ~/.claude/commands/ 또는 .claude/commands/
• 호출 방식: /command-name [arguments]
• 순차 실행: 정해진 순서대로 agent들을 오케스트레이션
• 워크플로우 정의: 복잡한 다단계 프로세스 자동화
• 품질 게이트: 각 단계별 검증 포인트 설정 가능

사용 예시

/bug-fix-workflow "User login fails with 500 error"

/feature-workflow "Create user authentication with JWT"

/code-review-workflow src/components/

장점

• ✅ 복잡한 워크플로우 자동화
• ✅ 일관된 프로세스 보장
• ✅ 여러 agent를 조율하는 오케스트레이션
• ✅ 재현 가능한 작업 흐름

단점

• ❌ 유연성 부족 (미리 정의된 순서)
• ❌ 수정하려면 파일 편집 필요
• ❌ 조건부 분기 구현이 복잡

3. Claude Code Plugins (최신 추가)

개념

모듈식 패키지 시스템으로, agents + commands + skills를 하나의 논리적 단위로 묶어 관리합니다.

구조

plugin-name/
├── agents/           # 관련 agents
│   ├── agent1.md
│   └── agent2.md
├── commands/         # 관련 commands
│   └── workflow.md
├── skills/           # 지식 패키지
│   ├── skill1.md
│   └── skill2.md
└── plugin.json       # 메타데이터

특징

• 위치: ~/.claude/plugins/ 또는 프로젝트 내
• 설치 방식:
• /plugin install python-development/plugin install kubernetes-operations
• 점진적 로딩: 필요할 때만 활성화 (progressive disclosure)
• 스킬 시스템: 자동 활성화되는 전문 지식 패키지
• 의존성 관리: 플러그인 간 의존성 정의 가능
• 마켓플레이스: 중앙화된 플러그인 저장소

Skills의 개념

---
name: kubernetes-deployment
type: skill
activates_on: ["kubernetes", "k8s", "deployment"]
---

# Kubernetes Deployment Skill
This skill provides specialized knowledge about...

• 특정 키워드나 컨텍스트에서 자동 활성화
• Agent에게 전문 지식을 "주입"
• 토큰 효율적 (필요할 때만 로드)

사용 예시

# 플러그인 설치
/plugin install python-development

# 자동 활성화
"Create a FastAPI microservice"
→ python-development 플러그인의 agents, skills 활성화
→ 관련 commands 사용 가능

# 플러그인 전용 명령어
/python-development:python-scaffold fastapi-microservice

장점

• ✅ 모듈화: 관련 기능을 논리적으로 그룹화
• ✅ 토큰 효율성: 필요한 것만 로드 (최소 토큰 사용)
• ✅ 버전 관리: 플러그인 단위로 업데이트
• ✅ 의존성 해결: 자동으로 필요한 플러그인 설치
• ✅ 컴포저빌리티: 여러 플러그인 조합 가능
• ✅ 배포 용이성: 팀 전체에 표준화된 도구 배포

단점

• ❌ 최신 기능 (일부 도구만 지원)
• ❌ 설정 복잡도 증가
• ❌ 플러그인 간 충돌 가능성

비교표

실제 사용 시나리오

Scenario 1: 단순 전문가 자문

"Review this code for security issues"

최적: Agent (security-auditor)

• 단일 전문가의 의견만 필요
• 빠르고 직접적

Scenario 2: 복잡한 다단계 프로세스

/feature-workflow "User authentication system"

최적: Command (workflow)

• 여러 단계를 거쳐야 함
• 품질 게이트 필요
• 일관된 프로세스 보장

Scenario 3: 특정 기술 스택 작업

/plugin install python-development
"Create a FastAPI app with SQLAlchemy"

최적: Plugin

• 관련된 모든 도구 한번에 활성화
• 자동으로 적절한 skills 로드
• 토큰 효율적

아키텍처 관점

Layer 구조

┌─────────────────────────────────────┐
│         Plugins (최상위)             │
│  - python-development                │
│  - kubernetes-operations             │
└────────────┬────────────────────────┘
             │ contains
    ┌────────┴─────────┐
    │                  │
┌───▼──────────┐  ┌───▼──────────┐
│   Agents     │  │  Commands    │
│  (전문가)     │  │ (워크플로우)  │
└──────────────┘  └──────────────┘
         │              │
         └──────┬───────┘
                │ uses
         ┌──────▼──────┐
         │   Skills    │
         │ (지식 패키지) │
         └─────────────┘

권장 사항

언제 Agent를 사용할까?

• ✅ 단일 전문가의 의견이 필요할 때
• ✅ 유연한 대화형 상호작용이 필요할 때
• ✅ 빠른 프로토타이핑

언제 Command를 사용할까?

• ✅ 반복적인 다단계 프로세스
• ✅ 팀 전체가 따라야 하는 표준 워크플로우
• ✅ 품질 게이트가 필요한 프로세스

언제 Plugin을 사용할까?

• ✅ 관련 기능을 패키지로 배포
• ✅ 토큰 효율성이 중요할 때
• ✅ 버전 관리와 의존성 해결이 필요할 때
• ✅ 대규모 팀에서 표준화된 도구 배포

진화 경로

2024 초반: Agents만 존재
    ↓
2024 중반: Commands 추가 (워크플로우 오케스트레이션)
    ↓
2024 후반/2025: Plugins 도입 (모듈화 + 토큰 효율성)

Plugins는 Agents와 Commands의 장점을 결합하면서 토큰 효율성과 배포 편의성을 크게 개선한 최신 접근 방식입니다.

첨부하신 bug-analyst.md는 Agent 형식이므로, Plugin 시스템으로 마이그레이션하면 다음과 같은 구조가 될 것입니다:

bug-analysis-plugin/
├── agents/
│   ├── bug-analyst.md
│   ├── error-detective.md
│   ├── code-diagnostician.md
│   └── fix-architect.md
├── commands/
│   └── bug-fix-workflow.md
├── skills/
│   ├── python-debugging.md
│   └── react-debugging.md
└── plugin.json

이렇게 구조화하면 /plugin install bug-analysis로 한번에 모든 버그 분석 도구를 활성화할 수 있습니다! 아참, Plugin은 Maketplace로 만들어야 됩니다. 다른 plugin 참고하세요.