Dannian's Warehouse

[회고] 1주차 회고 (2026.07.20 ~ 07.24)

Dannian — Mon, 27 Jul 2026 13:26:08 +0900

1주차 회고 (2026.07.20 ~ 07.24)

과정: 원티드 포텐업 AI Agent 트랙 4기
주제 키워드: 파이썬 기초 · Numpy/Pandas 입문 · AI 트렌드 감 잡기
한 줄 소감: 다시 학부생 때로 돌아간 느낌인데, 다만 술이 없는 학부생 느낌.
이번 주 숫자: 블로그 3편 · 자습 12개(심화 5+연습 7) · 과제 3 · 인포그래픽 3 · 인텔 5일

1. 이번 주 커리큘럼

날짜	학습 내용	그날의 트렌드
07.20	오리엔테이션 · Markdown	트렌드 소스·공모전 사이트
07.21	파이썬 기초 — 변수/자료형	AI 툴 3종(Alt·NotebookLM·Perplexity)
07.22	파이썬 기초 — 제어문	Agent의 발전(Orca/ADE), AI 생태계
07.23	파이썬 기초 — 함수/클래스	Loop Engineering, Gemini 3.6 Flash
07.24	Numpy & Pandas	지식 관리의 발전 — RAG

날짜별 상세: 07.20 · 07.21 · 07.22 · 07.23 · 07.24

2. 트렌드로 알게 된 것

AI 툴: Alt, NotebookLM, Perplexity — 실무 활용 감 잡기
에이전트: Orca / ADE(Agent Development Environment) — 여러 AI를 한 팀처럼 운영
엔지니어링 4단계: Prompt → Context → Harness → Loop Engineering
지식 관리: RAG(검색증강생성), Knowledge Graph, 파일 저장 포맷 변화(→ Markdown·JSON)
모델: Google Gemini 3.6 Flash 출시

3. 내가 한 것 (산출물)

과제: 제어문 · 함수 · 판다스
블로그 3편: 변수와 문자열 · 리스트와 튜플 · 딕셔너리·집합·불
자습: 클래스 심화(OOP 실무) 5편 + 연습문제 7제 — 수업 범위를 넘어 스스로 확장
인포그래픽 3건: AI 에이전트 트렌드 · AI 엔지니어링 트렌드 · 지식 저장 트렌드
데일리 인텔 파이프라인 구축: Slack에서 매일 AI 트렌드를 날짜별로 자동 수집·정리하는 체계 세팅

4. KPT 회고

Keep — 잘했고 계속할 것

매일 트렌드를 intel.md로 정리하는 습관 → 블로그·복습 자료가 자동으로 쌓임
수업 진도를 그날 블로그로 소화(3편) - 그 외는 차후 복습하며 추가로 작성 예정
자습으로 클래스 심화·연습문제까지 스스로 확장
앞으로 뭘 더 할지 지속적으로 상담 및 고민 할 것
1분 설명 카드를 만들기 위한 디자인 가이드라인 구축해두었고, 이를 통해서 보기 편하면서 핵심 내용들이 들어가있는 한장짜리 인포그래픽을 만들 수 있게 환경을 구축한 점.
위의 인포그래픽을 통해서 어디서든 참고하며 공부할 것

Problem — 어려웠거나 아쉬운 것

Pandas import 실패(스마트 앱 컨트롤)로 실습 시간 지연 → 해결 기록
RAG·Agent·Loop Engineering 등 새 용어가 한꺼번에 쏟아져 소화가 벅참
Pandas는 사용방식이 조금 생소해서 더 공부할 필요가 있음

Try — 다음에 시도할 것

새 용어는 그날 바로 "1분 설명" 카드로 정리하기
Numpy/Pandas를 실제 데이터셋에 적용해보기
데이터 전처리를 포함한 작업을 진행할 때 이번주에 부족한 부분이 보이면 추가 학습 진행할 것

5. 막혔던 것 & 해결

문제	원인	해결
Pandas `import` 시 `DLL load failed`	윈도우 스마트 앱 컨트롤이 DLL 차단	스마트 앱 컨트롤 끄고 VS Code 재시작

상세: 03.오류및해결_모음.md

6. 다음 주 목표

학습: 실제 CSV 데이터셋 1개로 로드 → 결측치 처리 → groupby 집계까지 한 사이클 완주 (이번 주 생소했던 Pandas loc/iloc 포함)
습관/태도: 새 용어는 당일 '1분 카드'로 즉시 정리하고, 수업 후 복습 루틴을 밀리지 않게 유지

7. 한 줄 정리

생소한 Python 언어 학습과 새로운 정보들로 정신없었지만, 재밌는 일주일이었으며, 추가로 모르는걸 바로 정리하려 하는 새로운 습관을 정립하기 좋은 시간이라고 생각했다.

[파이썬 기초 1편] 변수와 문자열 — 에러를 일부러 내면서 배운 것들

Dannian — Wed, 22 Jul 2026 18:43:25 +0900

[파이썬 기초 1편] 변수와 문자열 — 에러를 일부러 내면서 배운 것들

파이썬 기초 문법 시리즈
1편. 변수 / 숫자형 / 문자열 ← 현재 글
2편. 리스트 / 튜플
3편. 딕셔너리 / 집합 / 불

들어가며

데이터 분석 공부를 시작하면서 파이썬 기초 문법부터 다시 정리하고 있습니다.

처음엔 "변수? 문자열? 이런 건 그냥 읽고 넘어가면 되는 거 아닌가" 싶었는데, 막상 손으로 쳐보니 생각대로 안 되는 지점이 계속 나왔습니다. 그래서 이번 정리는 문법 나열 대신, 제가 실제로 걸려 넘어진 부분 위주로 남깁니다.

문법책을 눈으로 읽는 것과 셀을 직접 실행해서 빨간 에러를 보는 건 완전히 다른 경험이더군요.

1. 변수

변수는 결국 "이름표"

name = "홍길동"
position = "대리"
email = "steadywing01@gmail.com"
phone_number = "019-8928-1927"

print(name, position, email, phone_number)

홍길동 대리 steadywing01@gmail.com 019-8928-1927

여기까지는 어렵지 않습니다. 문제는 이름을 아무렇게나 지을 수 없다는 데서 시작했습니다.

규칙 1. 대소문자를 구분한다

Age = 30
age = 35
print(Age, age)

30 35

Age와 age는 완전히 다른 변수입니다. 사람 눈에는 같아 보여도 파이썬은 다르게 봅니다.

이게 왜 중요하냐면, 나중에 변수가 수십 개로 늘어났을 때 userName으로 저장해놓고 username으로 불러오는 실수를 하면 "분명히 저장했는데 왜 없다고 하지?" 하면서 한참 헤매게 됩니다. 실제로 제가 그랬습니다.

규칙 2. 특수문자와 숫자로 시작하는 이름은 안 된다

일부러 에러를 내봤습니다.

item?count = 5

SyntaxError: invalid syntax

100days = 100

SyntaxError: invalid decimal literal

밑줄(_)만 예외적으로 허용됩니다. 그래서 phone_number처럼 쓰는 겁니다.

규칙 3. ⚠️ 예약어를 변수로 쓰면 큰일 난다

이게 이번 실습에서 가장 인상 깊었던 부분입니다.

print = "hello"

print(print)

TypeError: 'str' object is not callable

무슨 일이 벌어진 걸까요?

print는 원래 함수입니다. 그런데 print = "hello"로 덮어쓰는 순간, print라는 이름표가 함수에서 떨어져 나와 "hello"라는 문자열에 붙어버립니다. 이제 print(...)를 호출하면 파이썬은 문자열을 함수처럼 호출하려고 시도하고, 당연히 실패합니다.

무서운 건 에러 메시지가 원인을 알려주지 않는다는 점입니다. 'str' object is not callable만 보고 "내가 print를 덮어썼구나"를 떠올리기는 쉽지 않습니다. 게다가 이 상태는 커널을 재시작하기 전까지 계속 유지되기 때문에, 이후에 작성하는 모든 코드에서 print가 고장난 채로 작업하게 됩니다.

list, str, sum, type, id 같은 이름들도 마찬가지입니다. list = [1, 2, 3]처럼 무심코 쓰기 쉬운 이름이라 더 위험합니다.

규칙 4. ⚠️ 주피터에서는 "셀 실행 순서"가 곧 코드 순서다

주피터 노트북을 쓰면서 처음 당황했던 지점입니다.

# 커널 재시작 직후 실행
print(name)

NameError: name 'name' is not defined

분명히 위쪽 셀에 name = "홍길동"이 눈에 보이는데도 에러가 납니다.

핵심은 이겁니다. 파이썬은 화면에 보이는 순서가 아니라, 내가 실행 버튼을 누른 순서대로 기억한다.

커널을 재시작하면 그동안 기억하던 변수가 전부 사라집니다. 화면의 코드는 그대로 남아있으니 "저장은 되어 있는데 왜?" 하고 착각하기 딱 좋습니다. 변수가 있는 셀을 다시 실행하면 정상 동작합니다.

name = "홍길동"   # 이 셀을 다시 실행한 뒤에
print(name)      # 이 셀을 실행하면 정상

홍길동

교훈: 노트북 작업 중 이상한 에러가 나면, 코드를 의심하기 전에 위에서부터 전부 다시 실행(Restart & Run All)해보는 게 빠릅니다.

2. 숫자형

정수와 실수

x = 5
y = -8
z = 0

print(x, y, z)
print(type(x), type(y), type(z))

5 -8 0
<class 'int'> <class 'int'> <class 'int'>

a = 3.14
b = -0.5
c = 1.0

print(type(a), type(b), type(c))

<class 'float'> <class 'float'> <class 'float'>

1.0처럼 소수점 아래가 0이어도 점이 찍혀 있으면 실수(float) 입니다. 이 구분은 나중에 나눗셈에서 다시 발목을 잡습니다.

큰 숫자는 밑줄로 끊어 읽자

money = 100_000_000_000_000
print(money)

100000000000000

100000000000000을 눈으로 세는 건 고문입니다. 파이썬은 숫자 사이의 밑줄을 그냥 무시하기 때문에, 읽기 좋은 위치에 끊어 쓸 수 있습니다. 출력할 때는 밑줄 없이 나옵니다.

재밌는 건 밑줄 위치가 3자리 단위일 필요도 없다는 점입니다.

money2 = 100_00_0_000_000_000
print(money2)

100000000000000

문법적으로는 통과하지만, 이렇게 쓰면 읽기 편하라고 만든 기능의 취지를 정면으로 배신하는 셈입니다.

지수 표현은 결과가 float이다

num = 1.0e3
print(num)

1000.0

num_under  = 2e+10
num_under2 = 2e-10
num_under3 = 0.000000321000011

print(num_under, num_under2, num_under3)
print(type(num_under), type(num_under2), type(num_under3))

20000000000.0 2e-10 3.21000011e-07
<class 'float'> <class 'float'> <class 'float'>

여기서 두 가지가 눈에 띄었습니다.

2e+10은 지수 표기로 썼지만 출력은 20000000000.0으로 풀려서 나옵니다.
반대로 0.000000321000011은 그냥 소수로 썼는데 출력은 3.21000011e-07로 지수 표기가 됩니다.

즉, 내가 어떻게 썼는지와 파이썬이 어떻게 보여주는지는 별개입니다. 파이썬은 "그 숫자를 가장 짧게 표현하는 방식"을 알아서 고릅니다. 값 자체는 동일하니 헷갈리지 않으면 됩니다.

정수 + 실수 = 실수

num1 = 10      # int
num2 = 1.0     # float

result = num1 + num2
print(result, type(result))

11.0 <class 'float'>

정수와 실수를 섞으면 더 정밀한 쪽인 실수로 통일됩니다. 정수 쪽에 맞춰 소수점을 버리면 정보가 사라지니까요.

산술 연산 7종

num1 = 10
num2 = 3

print(num1 + num2)   # 13   덧셈
print(num1 - num2)   # 7    뺄셈
print(num1 * num2)   # 30   곱셈
print(num1 / num2)   # 3.3333333333333335   나눗셈
print(num1 // num2)  # 3    몫
print(num1 % num2)   # 1    나머지
print(num1 ** num2)  # 1000 거듭제곱

여기서 중요한 포인트 하나. 10 / 3은 나누어떨어지지 않으니 실수가 되는 게 당연해 보이는데, 사실 파이썬 3의 /는 나누어떨어져도 무조건 실수를 돌려줍니다.

print(10 / 5)    # 2.0  (2가 아님!)
print(10 // 5)   # 2

정수 결과가 꼭 필요하면 //를 써야 합니다. 이걸 모르고 /를 쓰면 인덱스 자리에 실수가 들어가서 TypeError가 나는데, 나중에 리스트를 다룰 때 실제로 마주치게 됩니다.

복합 연산자

money = 0

money += 2000   # money = money + 2000
money -= 500
money *= 3
money /= 3      # ← 여기서 사고 발생
money **= 2
money //= 10
money %= 10

각 단계의 값을 찍어보면 이렇습니다.

연산	결과
`money += 2000`	`2000`
`money -= 500`	`1500`
`money *= 3`	`4500`
`money /= 3`	`1500.0` ← 여기서 실수로 변함
`money **= 2`	`2250000.0`
`money //= 10`	`225000.0`
`money %= 10`	`0.0`

money /= 3을 지나는 순간 4500이 1500.0이 됩니다. 값은 같아 보이지만 타입이 int에서 float로 바뀐 거고, 이후 모든 연산이 float로 끌려갑니다. 마지막 //와 %까지도 225000.0, 0.0처럼 소수점이 붙어서 나오죠.

돈 계산처럼 정수로 딱 떨어져야 하는 값에서 이런 일이 생기면 곤란합니다. 나눗셈 한 번이 타입 전체를 오염시킨다는 걸 기억해둘 만합니다.

예제 1. 페이지네이션 — `//`와 `%`를 같이 쓰는 대표 사례

게시물 100개를 한 페이지에 30개씩 보여주려면 총 몇 페이지가 필요할까?

100 // 30 = 3. 그런데 3페이지만 만들면 남는 10개는 어디에도 못 보여줍니다. 나머지가 있으면 페이지 하나를 더 만들어야 합니다.

post = 100
post_per_page = 30

page_num = post // post_per_page          # 3
if post % post_per_page != 0:
    page_num += 1                          # 나머지 10개를 위한 4페이지

print(page_num)

한 줄로 줄이면 이렇게 됩니다.

page_num = (post // post_per_page) + (0 if post % post_per_page == 0 else 1)

//(전체 몫)와 %(남은 것)를 짝으로 쓰는 패턴은 페이지 나누기, 배치 처리, 시간 변환(초 → 분/초) 등에서 계속 나옵니다. 그냥 연산자 두 개가 아니라 하나의 관용구로 외워두는 게 좋겠더군요.

예제 2. 홀짝 판별

birth_year = 1982
remainder = birth_year % 2   # 0이면 짝수, 1이면 홀수

if remainder == 0:
    print("짝수")
else:
    print("홀수")

짝수

% 2는 홀짝 판별의 표준 관용구입니다. 확장하면 % 3 == 0은 3의 배수, % 100 == 0은 100단위 판별이 됩니다.

3. ⭐ 문자열

데이터 분석에서 가장 많이 만지게 되는 자료형입니다. 실제로 수집한 데이터는 거의 다 문자열 상태로 들어옵니다.

따옴표 안에 따옴표 넣기

message1 = "I'm happy"
message2 = 'I\'m happy'

print(message1)
print(message2)

I'm happy
I'm happy

방법이 두 가지입니다.

바깥 따옴표를 다른 걸로 쓴다 — 안에 '가 있으면 바깥은 "로. 가장 깔끔합니다.
백슬래시로 탈출시킨다 — \'는 "이건 문자열 끝이 아니라 그냥 작은따옴표 글자야"라는 표시입니다.

줄바꿈과 여러 줄 문자열

print("안녕하세요.\n제 이름은 홍길동 입니다")

안녕하세요.
제 이름은 홍길동 입니다

긴 글은 따옴표 3개를 씁니다. 그런데 여기에 함정이 있습니다.

review = """
test text
text test
"""
print(review)


test text
text test

위아래로 빈 줄이 하나씩 생깁니다. """ 바로 뒤의 줄바꿈과 마지막 줄바꿈까지 전부 문자열에 포함되기 때문입니다.

이걸 없애려면 줄 끝에 백슬래시를 붙입니다.

review = '''\
짜장면이 너무너무 맛있는데,
기사 아저씨가 너무 불친절했어요.\
'''
print(review)

짜장면이 너무너무 맛있는데,
기사 아저씨가 너무 불친절했어요.

줄 끝의 \는 "이 줄바꿈은 문자열에 넣지 마" 라는 뜻입니다. 코드에서는 들여쓰기 없이 예쁘게 쓰면서, 실제 문자열에는 불필요한 공백을 안 넣는 방법입니다.

문자열 연산 — 덧셈과 곱셈

text1 = "hello"
text2 = "python"

print(text1 + text2)

hellopython

print("=" * 50)
print("best" * 3)

==================================================
bestbestbest

"=" * 50은 구분선 만들 때 정말 자주 씁니다. 반복문 안에서 로그를 찍을 때 유용합니다.

print("=" * 50)
print("Loop 1.")
print("=" * 50)

단, 문자열 × 문자열은 안 됩니다.

print(text1 * text2)

TypeError: can't multiply sequence by non-int of type 'str'

곱셈은 "몇 번 반복할지"를 정수로 받아야 하는데, "python"은 횟수가 될 수 없으니까요.

길이 재기 — 눈에 안 보이는 공백을 찾는 법

message = "hello"
print(len(message))

len()이 진짜 유용해지는 순간은 이겁니다.

text1 = "홍길동"
text2 = "홍길동 "    # 뒤에 공백 하나

print(text1, len(text1))
print(text2, len(text2))

홍길동 3
홍길동  4

출력만 보면 완전히 똑같아 보이는데 길이가 다릅니다.

이게 실무에서 왜 중요하냐면, "홍길동"과 "홍길동 "은 파이썬 입장에서 다른 값입니다. 비교하면 False가 나오고, 딕셔너리 키로 쓰면 다른 키가 되고, 데이터를 합칠 때 매칭이 안 됩니다. "분명히 같은 이름인데 왜 조인이 안 되지?"의 범인이 대부분 이 눈에 안 보이는 공백입니다.

의심스러울 땐 len()으로 찍어보는 게 가장 확실합니다.

인덱싱 — 앞에서 세기, 뒤에서 세기

문자열은 글자마다 번호가 붙어 있습니다. 0부터 시작합니다.

문자     9    0    1    2    1    2    -    1    3    2    5    2    2    1
앞에서   0    1    2    3    4    5    6    7    8    9   10   11   12   13
뒤에서 -14  -13  -12  -11  -10   -9   -8   -7   -6   -5   -4   -3   -2   -1

앞에서 셀 땐 0부터, 뒤에서 셀 땐 -1부터 시작합니다. 뒤에서 셀 때 -0이 없으니 -1부터인 거죠.

문제. 주민등록번호에서 성별 자리를 뽑아보세요.

regist_num = "901212-1325221"

print(regist_num[7])    # 1
print(regist_num[-7])   # 1

같은 글자에 두 개의 주소가 있는 셈입니다. 어느 쪽을 쓸지는 상황에 따라 다릅니다.

문자열 길이가 항상 같다면(주민번호처럼) → 앞에서 세는 게 직관적
뒤쪽이 고정이고 앞쪽 길이가 들쭉날쭉하다면 → 뒤에서 세는 게 안전

슬라이싱 — `[시작:끝]`, 끝은 포함 안 됨

문제. 주민등록번호에서 생년월일을 뽑아보세요.

regist_num = "901212-1325221"

print(regist_num[0:6])   # 901212
print(regist_num[:6])    # 901212  (시작 생략 = 처음부터)
print(regist_num[6:])    # -1325221 (끝 생략 = 끝까지)

가장 헷갈렸던 게 끝 번호는 포함되지 않는다는 규칙이었습니다. [0:6]은 0,1,2,3,4,5번째 글자만 가져오고 6번은 안 가져옵니다.

처음엔 불친절하다고 생각했는데, 익숙해지니 오히려 편했습니다. 끝 번호 - 시작 번호 = 가져온 개수가 딱 맞아떨어지거든요. [0:6]은 고민할 것 없이 6글자입니다.

음수 인덱스와도 섞어 쓸 수 있습니다.

print(regist_num[2:6])      # 1212
print(regist_num[-12:-8])   # 1212
print(regist_num[-12:6])    # 1212  (음수 시작 + 양수 끝도 가능)

예제. 주민번호 마스킹

문제. 주민등록번호 뒷자리에서 성별 자리만 남기고 나머지를 *로 가려주세요.

regist_num = "901212-1325221"

temp = regist_num[:8]    # 901212-1  (생년월일 + 성별까지)
stars = "*" * 6          # ******

print(temp + stars)

901212-1******

슬라이싱으로 자르고, 곱셈으로 별을 만들고, 덧셈으로 붙이는 3단 조합입니다. 개인정보 마스킹은 실무에서 꼭 필요한 처리라 패턴 자체를 기억해둘 만합니다.

⭐ f-string — 문자열 포매팅

이건 "왜 필요한가"를 실패에서 출발해야 이해가 됩니다.

시도 1. 그냥 더해보기

name = "홍길동"
age = 24

print(name + age)

TypeError: can only concatenate str (not "int") to str

문자열 + 숫자는 안 됩니다. 파이썬 입장에서 +가 "이어붙이기"인지 "더하기"인지 알 수 없거든요.

시도 2. str()로 변환해서 더하기

print(name + "(" + str(age) + ")")

홍길동(24)

동작은 합니다. 그런데 따옴표와 +가 뒤엉켜서 읽기가 괴롭습니다. 변수가 다섯 개쯤 되면 사람이 읽을 수 있는 코드가 아니게 됩니다.

시도 3. f-string

print(f"{name}({age})")
print(f"{name}님 안녕하세요.")

홍길동(24)
홍길동님 안녕하세요.

문자열 앞에 f를 붙이고, 중괄호 안에 변수를 넣으면 끝입니다. 결과물의 모양이 코드에 그대로 보인다는 게 최고의 장점입니다. str() 변환도 알아서 해줍니다.

accuracy = 0.8
print(f"Accuracy: {accuracy}")

Accuracy: 0.8

중괄호 안에는 변수뿐 아니라 식도 들어갑니다.

print(f"정확도: {accuracy * 100}%")
print(f"합계: {10 + 20}")

정확도: 80.0%
합계: 30

앞으로 문자열을 조립할 일이 있으면 고민 없이 f-string을 쓰기로 했습니다.

4. 문자열 메서드 — 데이터 전처리의 도구들

여기서부터는 "문법"이라기보다 실제로 지저분한 데이터를 청소하는 도구에 가깝습니다.

⭐ split() — 문자열 쪼개기

address1 = '서울시  관악구 신림동'    # 서울시 뒤에 공백 2개
address2 = '강남구/동작구/노원구'

print(address1.split())
print(address1.split(' '))
print(address2.split('/'))

['서울시', '관악구', '신림동']
['서울시', '', '관악구', '신림동']
['강남구', '동작구', '노원구']

여기가 이번 실습에서 두 번째로 인상 깊었던 지점입니다.

split()과 split(' ')는 같아 보이지만 결과가 다릅니다.

split() — 인자 없이 쓰면 연속된 공백을 하나로 묶어서 처리하고, 빈 값도 안 만듭니다.
split(' ') — 공백 하나를 정확히 구분자로 봅니다. 공백이 두 개면 그 사이에 빈 문자열 ''이 끼어듭니다.

실무 데이터는 공백이 두 개, 세 개씩 들어있는 경우가 흔합니다. 그래서 공백으로 자를 때는 인자 없이 split()을 쓰는 게 안전합니다. 저는 이걸 모르고 split(' ')을 쓰다가 빈 문자열이 섞인 리스트를 받고 한참 봤습니다.

예제. 파일 확장자 분리

file_name1 = "수업자료.pdf"
file_name2 = "수업자료_복습.ipynb"

print(file_name1.split("."))
print(file_name2.split("."))

['수업자료', 'pdf']
['수업자료_복습', 'ipynb']

split()의 결과는 항상 리스트입니다. 그래서 파일명은 [0], 확장자는 [-1]로 꺼냅니다.

참고로 "보고서.최종.v2.xlsx"처럼 점이 여러 개면 ['보고서', '최종', 'v2', 'xlsx']가 되므로, 확장자는 [1]이 아니라 [-1]로 꺼내는 게 안전합니다.

replace() — 문자열 바꾸기

message = "오늘의 날씨는 맑음"
result = message.replace("맑음", "흐림")

print(result)

오늘의 날씨는 흐림

여기서 꼭 짚고 갈 것: replace()는 원본을 바꾸지 않습니다. 바뀐 새 문자열을 돌려줄 뿐입니다.

message.replace("맑음", "흐림")
print(message)     # 오늘의 날씨는 맑음  ← 그대로!

문자열은 한 번 만들면 못 바꾸는(immutable) 자료형이라 그렇습니다. 반드시 결과를 변수에 다시 담아야 합니다. 이건 뒤에 나올 strip(), lower(), upper()도 전부 동일합니다.

실전. 뒤죽박죽 성별 데이터 정리

수집된 성별 데이터가 이렇게 들어왔다고 해봅시다.

gender = "fffmmm여자mm남자f"

한글과 알파벳이 섞여 있습니다. 이걸 replace()를 연쇄로 써서 정리합니다.

result1 = gender.replace("여자", "f")
result2 = result1.replace("남자", "m")
print(result2)

fffmmmfmmmf

replace()가 문자열을 돌려주니까, 그 결과에 또 replace()를 붙일 수 있습니다. 그래서 이렇게 한 줄로도 됩니다.

print(gender.replace("여자", "f").replace("남자", "m"))

이걸 응용하면 붙어있는 데이터를 낱개로 분리할 수도 있습니다.

print(result2.replace("f", "f ").replace("m", "m "))
print(result2.replace("f", "f ").replace("m", "m ").split())

f f f m m m f m m m f 
['f', 'f', 'f', 'm', 'm', 'm', 'f', 'm', 'm', 'm', 'f']

구분자가 없어서 자를 수 없던 문자열에, replace로 공백을 심어놓고 split으로 자르는 발상입니다. 처음 봤을 때 "이런 식으로도 푸는구나" 싶었습니다.

실전. 리뷰에서 노이즈 제거

review = "이거 진짜 웃기닼ㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋ"
print(review.replace("ㅋ", ""))

이거 진짜 웃기닼

replace(찾을것, "")은 삭제입니다. 빈 문자열로 바꾼다 = 지운다. 텍스트 분석 전에 의미 없는 문자를 걷어낼 때 쓰는 기본 기술입니다.

lower() / upper() — 대소문자 통일

gender = "f,F,f,m,M,m,F,f,M,M"

print(gender.lower())
print(gender.upper())

f,f,f,m,m,m,f,f,m,m
F,F,F,M,M,M,F,F,M,M

같은 성별인데 f와 F로 따로 집계되면 안 되니, 세기 전에 한쪽으로 통일하는 게 먼저입니다. 이메일이나 아이디 비교에서도 필수 전처리입니다.

strip() / lstrip() / rstrip() — 공백 제거

name = "             홍길동                    "

print(f"|{name.strip()}|")     # 양쪽
print(f"|{name.lstrip()}|")    # 왼쪽만
print(f"|{name.rstrip()}|")    # 오른쪽만

|홍길동|
|홍길동                    |
|             홍길동|

작은 팁: 결과를 | 사이에 끼워서 출력한 것에 주목하세요. 공백은 눈에 안 보이기 때문에, 이렇게 경계 문자로 감싸야 얼마나 지워졌는지 확인할 수 있습니다. len()과 함께 공백 디버깅의 필수 기술입니다.

이름 앞뒤의 공백은 사용자 입력에서 정말 흔하게 들어옵니다. 앞서 본 "홍길동" vs "홍길동 " 문제를 떠올려보면, 입력받은 문자열은 일단 strip()부터 거는 습관이 왜 필요한지 알 수 있습니다.

count() — 개수 세기

gender = "F,F,F,M,M,M,F,F,M,M"

print(gender.count("F"))   # 5
print(gender.count("M"))   # 5
print(gender.count("m"))   # 0  ← 대소문자 구분!
print(gender.count("f"))   # 0
print(len(gender))         # 19

count()도 대소문자를 구분합니다. 그래서 세기 전에 lower()로 통일하는 게 순서입니다.

예제. 리뷰 키워드 빈도

review = """\
짬뽕은 정말 맵고 맛있었어요. 해산물이 가득 들어가서 만족했습니다.
짜장면은 이 집에서 먹어본 것 중 가장 맛있었어요
짜장면 굿\
"""

print(f"짜장면 등장 횟수: {review.count('짜장면')}")
print(f"짬뽕 등장 횟수: {review.count('짬뽕')}")

짜장면 등장 횟수: 2
짬뽕 등장 횟수: 1

⚠️ f-string 안에서 따옴표를 쓸 때는 바깥과 다른 종류를 써야 합니다. f"...{review.count('짜장면')}..."처럼 바깥이 "면 안쪽은 '로.

이게 텍스트 분석의 가장 원시적인 형태입니다. 여러 리뷰에 이걸 돌리면 "어떤 메뉴가 자주 언급되는가"를 알 수 있고, 그게 곧 워드클라우드나 키워드 분석의 출발점입니다.

1편 정리

오늘의 함정 4선

함정	증상	대응
예약어 덮어쓰기	`print = "hello"` 후 `'str' object is not callable`	`print`, `list`, `str`, `sum`, `type` 을 변수명으로 쓰지 않기
커널 재시작 후 NameError	코드가 화면에 보이는데도 "정의되지 않았다"	위에서부터 다시 실행(Restart & Run All)
`/` 나눗셈의 타입 오염	`4500`이 `1500.0`으로 변해서 이후 계산 전부 float	정수가 필요하면 `//`
`split(' ')`의 빈 문자열	공백 2개 사이에 `''`가 끼어듦	공백 기준이면 인자 없이 `split()`

손에 익혀야 할 것

문자열 메서드는 원본을 안 바꾼다 → 결과를 변수에 다시 담기
f-string → 문자열 조립은 무조건 이걸로
len()과 |{...}| → 눈에 안 보이는 공백 찾는 두 가지 기술
//와 %는 짝 → 페이지네이션, 홀짝, 단위 변환의 관용구
슬라이싱 [시작:끝], 끝은 미포함 → 대신 끝 - 시작 = 개수

다음 편에서는 여러 값을 한 번에 담는 리스트와 튜플을 정리합니다. lst[8:] = 10은 에러가 나는데 lst[8:] = "python"은 되는, 좀 이상한 이야기가 기다리고 있습니다.

[2편] 리스트와 튜플 — 슬라이스 대입이 이상하게 동작하는 이유

Personal AI Company 셋업 ⑤: 자동 wakeup 패턴으로 에이전트 파이프라인 직렬화하기

Dannian — Thu, 21 May 2026 09:00:52 +0900

왜 자동 wakeup이 필요한가

에이전트가 작업을 완료했는데 다음 단계가 시작되지 않는다면 파이프라인은 조용히 멈춘다. 사람이 대시보드를 계속 보면서 "Researcher 끝났으니까 이제 Creator 깨워야지"를 직접 수행하면 자동화가 아니다. 그것은 사람이 폴링하는 것이다.

Paperclip은 이 문제를 children API + tree-hold 조합으로 해결한다. CEO가 child 이슈를 올바르게 등록하고 자신을 blocked 상태로 두면, child가 완료될 때 Paperclip이 CEO를 자동으로 깨운다. 이 메커니즘이 제대로 작동하려면 정확한 API 호출 순서와 상태 관리가 필요하다.

children API가 자동 wakeup의 열쇠다

Paperclip에서 이슈를 만드는 방법은 두 가지다. 이 둘은 겉보기에 비슷하지만 자동 wakeup 관점에서 완전히 다르게 동작한다.

항목	`POST /api/issues/{id}/children`	`POST /api/issues`
parent_id 자동 연결	✅ 자동	❌ 없음
자동 wakeup 트리거	✅ child done 시 parent wakeup	❌ 동작 안 함
조직 트리 표시	✅ parent 아래 계층 표시	❌ 독립 이슈로 표시
권한 컨텍스트 상속	✅ parent 컨텍스트 상속	❌ 독립 컨텍스트
tree-hold 연동	✅ 동작	❌ 동작 안 함
파이프라인 사용 가능 여부	✅ 필수 사용	❌ 사용 금지

POST /api/issues로 만든 이슈는 parent_id가 없다. Paperclip이 해당 이슈의 완료를 누구에게도 알릴 의무가 없으므로 parent는 영원히 blocked 상태에 머문다. children 엔드포인트를 사용해야 parent_id가 자동으로 설정되고 완료 시 parent 이슈가 wakeup 큐에 올라간다.

children API 호출 예시는 다음과 같다.

curl -X POST https://api.paperclip.sh/api/issues/{parentIssueId}/children \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assigneeAgentId": "{researcherAgentId}",
    "title": "[Researcher] 5편 wakeup 패턴 조사",
    "description": "... 위임 메시지 전체 ..."
  }'

tree-hold 패턴: blocked + tree-hold는 한 쌍이다

child 이슈를 만든 것만으로는 부족하다. CEO 이슈가 계속 in_progress 상태라면 다음 heartbeat에서 CEO가 깨어나 다음 작업을 시작할 수 있다. child 완료를 기다리지 않고 Creator child를 먼저 만들어버리는 문제가 발생한다.

두 가지 API를 순서대로 호출해야 한다.

① 이슈 상태를 blocked로 변경

curl -X PATCH https://api.paperclip.sh/api/issues/{parentIssueId} \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked"}'

② tree-hold 등록

curl -X POST https://api.paperclip.sh/api/issues/{parentIssueId}/tree-holds \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "pause",
    "reason": "waiting for child {childIssueId} (Researcher 완료 대기)"
  }'

mode: "pause"는 child가 완료되면 tree-hold가 자동으로 해제되는 방식이다. blocked 상태는 "외부 의존성 때문에 진행 불가"라는 신호이고, tree-hold는 실행 큐에 "내가 풀 때까지 이 이슈를 깨우지 말라"는 잠금이다. 둘 중 하나만 설정해도 예상과 다른 동작이 발생한다.

직렬 처리 강제 패턴

동시에 만들면 생기는 문제

조사→생성→검증→실행의 4단계 파이프라인이 있다고 가정하자. CEO가 한 번에 4개 child를 만들면 다음 상황이 발생한다.

CEO → Researcher, Creator, Reviewer, Executor 동시 생성
         ↓           ↓          ↓           ↓
     (리서치 중)  (참조할     (참조할     (참조할
                  리서치 없음) 초안 없음)  검수 없음)

Creator는 Researcher의 산출물 경로를 참조해야 하지만 실행 시점에 해당 파일이 존재하지 않는다. 결과는 에러이거나 잘못된 산출물이다. 직렬 처리는 설계 취향의 문제가 아니라 의존성 때문에 반드시 지켜야 하는 제약이다.

올바른 직렬 처리 흐름

CEO 이슈 (in_progress)
  │
  ├─ [Step 1] POST /children → Researcher child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Researcher done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  ├─ [Step 2] 리서치 산출물 확인 후
  │           POST /children → Creator child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Creator done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  ├─ [Step 3] 초안 확인 후
  │           POST /children → Reviewer child 생성
  │     ↓
  │  CEO → blocked + tree-hold 등록
  │     ↓ (Reviewer done)
  │  [자동 wakeup] CEO → in_progress 복귀
  │
  └─ [Step 4] 검수 통과 확인 후 CEO → done

핵심 원칙은 하나다: 다음 child는 이전 child가 done이 된 후에만 만든다.

CEO 관점 전체 시퀀스

# 1단계: 에이전트 ID 조회
curl https://api.paperclip.sh/api/companies/{companyId}/agents \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
# → Researcher의 agentId 확인

# 2단계: child 이슈 생성
curl -X POST https://api.paperclip.sh/api/issues/{myCEOIssueId}/children \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigneeAgentId": "{researcherAgentId}", "title": "...", "description": "..."}'
# → childIssueId 저장

# 3단계: 내 이슈를 blocked로
curl -X PATCH https://api.paperclip.sh/api/issues/{myCEOIssueId} \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "blocked"}'

# 4단계: tree-hold 등록 (즉시)
curl -X POST https://api.paperclip.sh/api/issues/{myCEOIssueId}/tree-holds \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "pause", "reason": "waiting for child {childIssueId}"}'

# → Paperclip이 Researcher를 wakeup
# → Researcher done → CEO 자동 wakeup

이 시리즈 자체가 작동 증거다

이 블로그 시리즈(Personal AI Company 셋업)는 위 패턴을 그대로 적용해 운영한다. 각 편의 작성 흐름은 다음 구조를 따른다.

CEO 이슈: 블로그 N편 작성
  │
  ├─ child: [Researcher] N편 조사
  │     → /app/workspace/blog-personal-ai-company-setup/research/{N편}.md
  │     → done → CEO 자동 wakeup
  │
  ├─ child: [Creator] N편 초안 작성
  │     → /app/workspace/blog-personal-ai-company-setup/drafts/{N편}.md
  │     → done → CEO 자동 wakeup
  │
  └─ child: [Reviewer] N편 검수
        → /app/workspace/blog-personal-ai-company-setup/reviews/{N편}-review.md
        → done → CEO 최종 보고

각 편의 리서치 파일이 /app/workspace/ 아래에 실제로 존재하고 Creator인 내가 지금 이 글을 쓰고 있다는 사실 자체가 패턴이 작동했다는 증거다.

에이전트가 스스로 blocked를 선택하는 이유

"왜 에이전트가 스스로 blocked 상태로 가는가?"라는 질문이 처음에는 어색하게 느껴질 수 있다. blocked는 보통 "문제가 생긴 상태"로 인식되기 때문이다.

Paperclip에서 blocked는 의도적인 대기 신호다. "나는 다음 단계를 알고 있지만, 선행 조건이 충족될 때까지 실행하지 않겠다"는 명시적 선언이다. 에이전트가 blocked를 선택하지 않으면 시스템은 에이전트가 계속 작업할 수 있다고 판단하고, 다음 heartbeat에서 불완전한 상태로 진행을 강제한다. blocked + tree-hold는 "올바른 순서를 강제하는 자기 제어 메커니즘"이다.

트러블슈팅: wakeup 실패 시나리오 3가지

시나리오 1: child를 일반 API로 만든 경우

증상: Researcher가 done이 됐는데 CEO 이슈가 계속 blocked 상태다.

원인: POST /api/issues 또는 POST /api/companies/{id}/issues로 child를 만들어서 parent_id가 없다. Paperclip이 완료를 parent에게 알리지 않는다.

해결책:

Board가 대시보드에서 CEO 이슈 status를 todo → in_progress로 수동 변경한다.
CEO가 깨어난 후 리서치 산출물 경로를 직접 확인한다.
이후 단계부터 반드시 /api/issues/{id}/children 엔드포인트를 사용한다.

시나리오 2: blocked 처리를 잊은 경우

증상: CEO가 Researcher child를 만들었는데 Researcher 완료 전에 Creator child도 생성됐다. Creator가 리서치 파일 없이 실행된다.

원인: child 생성 후 blocked 상태로 변경하지 않아 다음 heartbeat에서 CEO가 다음 단계를 진행했다.

해결책:

잘못 생성된 Creator child 이슈를 cancelled로 변경한다.
Researcher가 완료될 때까지 CEO 이슈를 수동으로 blocked 상태로 유지한다.
Researcher 완료 후 Board가 CEO 이슈를 수동 unblock한다.
CEO가 리서치 산출물을 확인한 후 Creator child를 재생성한다.

시나리오 3: tree-hold 해제 후에도 wakeup이 오지 않는 경우

증상: child가 done이 됐고 tree-hold도 해제됐는데 CEO 이슈가 in_progress로 돌아오지 않는다.

원인: 자동 wakeup 메커니즘의 현재 알려진 제약이다. 버그가 아니며, Paperclip에서 개선 예정 기능이다.

해결책:

Board가 대시보드에서 CEO 이슈와 child 이슈의 상태를 확인한다.
Child가 실제로 done인지 확인한다.
CEO 이슈 status를 todo 또는 in_progress로 수동 변경한다.
CEO가 깨어나면 child 산출물 경로를 확인하고 다음 단계를 진행한다.

현재 운영 중에는 Board(사용자)가 대시보드를 주기적으로 확인해 stuck 이슈를 수동으로 unblock하는 것을 권장한다.

패턴 체크리스트

파이프라인 구성 시 다음 순서를 반드시 지킨다.

POST /api/issues/{id}/children 으로 child 생성 (POST /api/issues 금지)
child 생성 직후 PATCH /api/issues/{id} 로 parent를 blocked 상태로 변경
blocked 변경 직후 POST /api/issues/{id}/tree-holds 로 mode: "pause" 등록
다음 child는 이전 child가 done이 된 후에만 생성
자동 wakeup 실패 대비: Board가 대시보드를 주기적으로 모니터링

다음 편 예고

6편에서는 Telegram bridge로 AI 에이전트 팀을 모바일에서 원격 제어하는 방법을 다룬다. polling과 webhook의 선택 기준, callback_data 64바이트 제약 해결 패턴, 화이트리스트 기반 접근 제어, Paperclip API 연동 흐름을 설명한다.

# Personal AI Company 셋업 ④: Path B — 에이전트 간 파일 공유의 해법

Dannian — Wed, 20 May 2026 23:00:15 +0900

Researcher가 조사를 마치고 "저장 완료"를 보고했다. Creator가 해당 파일을 읽으려 했는데 파일이 없다. 에이전트 로그에는 Write 도구 호출이 성공으로 기록되어 있다. 이 시리즈 4편에서는 이 현상의 원인과 해법, 절대경로 규칙의 필요성을 실제 프로젝트 구조를 기반으로 설명한다.

문제 인식: 에이전트는 왜 서로의 파일을 못 찾는가

per-agent sandbox의 구조

Paperclip의 각 에이전트는 독립된 실행 환경(sandbox)에서 작동한다. 에이전트가 실행될 때마다 격리된 git worktree 또는 operator branch가 할당되며, 상대경로(./workspace/)는 이 격리 디렉토리를 기준으로 resolve된다.

에이전트 A (Researcher) CWD: /paperclip/workspaces/run-20260518-001/
에이전트 B (Creator)    CWD: /paperclip/workspaces/run-20260518-002/

A에서 ./workspace/research/output.md
  = /paperclip/workspaces/run-20260518-001/workspace/research/output.md

B에서 ./workspace/research/output.md
  = /paperclip/workspaces/run-20260518-002/workspace/research/output.md

같은 상대경로가 물리적으로 서로 다른 파일을 가리킨다. Researcher가 상대경로로 저장했다면, Creator는 그 파일을 읽을 수 없다.

상대경로가 실패하는 두 가지 경우

에이전트의 Write 도구 호출이 성공으로 기록되어도 다른 에이전트가 파일을 찾지 못하는 경우는 두 가지다.

에이전트가 상대경로를 사용해 자신의 격리 sandbox에 저장했다.
격리 sandbox는 heartbeat 간 상태 유지를 보장하지 않아, 다음 실행에서 파일이 사라졌다.

두 경우 모두 공유 경로 미사용이 근본 원인이다.

Path B: 공유 워크스페이스 개념

host bind-mount란 무엇인가

/app/workspace/는 호스트 파일시스템의 특정 디렉토리를 모든 에이전트 컨테이너에 동일하게 마운트한 공유 경로다. 아래는 docker-compose 기반 설정 예시다.

# docker-compose.yml
services:
  paperclip:
    volumes:
      - /host/data/workspace:/app/workspace

컨테이너 내부에서 /app/workspace/를 읽거나 쓰면, 그 변경이 호스트 파일시스템(/host/data/workspace/)에 그대로 반영된다. 어떤 컨테이너에서 쓰든 같은 물리 위치에 기록된다.

/app/workspace/가 공유 채널이 되는 이유

모든 에이전트는 동일한 /app/workspace/ 마운트 포인트를 가진다. Researcher가 /app/workspace/blog-project/research/output.md에 저장하면, Creator는 같은 절대경로로 그 파일을 읽을 수 있다.

[Researcher sandbox]
/app/workspace/blog/research/output.md
  = /host/data/workspace/blog/research/output.md  ← 동일 물리 경로

[Creator sandbox]
/app/workspace/blog/research/output.md
  = /host/data/workspace/blog/research/output.md  ← 동일 물리 경로

에이전트가 어떤 격리 sandbox에서 실행되더라도 /app/workspace/는 항상 같은 물리 위치를 가리킨다.

Path A(sandbox) vs Path B(공유) 비교

구분	Path A — per-agent sandbox	Path B — 공유 워크스페이스
경로 형식	상대경로 (`./workspace/`)	절대경로 (`/app/workspace/`)
물리 위치	에이전트마다 다름	모든 에이전트 공유
에이전트 간 파일 공유	불가	가능
Heartbeat 간 영속성	보장 안 됨	보장됨
용도	임시 스크래치	공식 산출물 저장

절대경로 규칙: 5개 에이전트의 공통 약속

5개 에이전트(CEO, Researcher, Creator, Reviewer, Executor)는 각각의 시스템 프롬프트에 동일한 절대경로 규칙 섹션을 가진다. 실제 시스템 프롬프트에서 발췌한 CEO의 규칙은 다음과 같다.

## ⚠️ 절대경로 규칙 (최우선)

모든 파일 참조는 호스트와 공유되는 절대경로를 사용한다.
본인의 격리 workspace(상대경로 ./workspace/)는 임시 스크래치 용도로만 쓴다.

| 종류              | 절대경로                                     |
|-------------------|----------------------------------------------|
| 스킬 파일         | /app/skills/{name}.md                        |
| Researcher 산출물 | /app/workspace/{project-name}/research/      |
| Creator 산출물    | /app/workspace/{project-name}/drafts/        |
| Reviewer 산출물   | /app/workspace/{project-name}/reviews/       |
| Executor 최종본   | /app/workspace/{project-name}/final/         |

CEO가 정의하는 {project-name}

CEO는 새 프로젝트 시작 시 {project-name}을 결정하고 위임 메시지에 명시한다. 나머지 에이전트는 CEO가 지정한 프로젝트명을 임의로 변경하지 않는다. 이 규칙 하나가 파이프라인 전체의 경로 일관성을 보장한다.

역할별 읽기/쓰기 경로 매핑

CEO:        읽기 — 모든 하위 디렉토리
Researcher: 쓰기 — /app/workspace/{project}/research/
            읽기 — /app/skills/
Creator:    쓰기 — /app/workspace/{project}/drafts/
            읽기 — /app/workspace/{project}/research/, /app/skills/
Reviewer:   쓰기 — /app/workspace/{project}/reviews/
            읽기 — research/, drafts/, /app/skills/
Executor:   쓰기 — /app/workspace/{project}/final/
            읽기 — drafts/, reviews/

실제 디렉토리 구조

research/ → drafts/ → reviews/ → final/ 4단계

디렉토리 구조는 파이프라인 단계와 1:1로 대응한다.

/app/workspace/{project-name}/
├── research/    # Researcher 산출물 → Creator, Reviewer가 읽음
├── drafts/      # Creator 산출물  → Reviewer, Executor가 읽음
├── reviews/     # Reviewer 산출물 → Executor가 읽음
└── final/       # Executor 최종본 → Board 승인 후 외부 발행

현 블로그 프로젝트 구조 예시

이 시리즈를 작성하면서 실제로 생성된 구조다.

/app/workspace/blog-personal-ai-company-setup/
│
├── research/
│   ├── 01-why-ai-company.md
│   ├── 02-paperclip-setup.md
│   ├── 03-agent-design.md
│   └── 04-shared-workspace.md
│
├── drafts/
│   ├── 01-why-ai-company.md
│   ├── 02-paperclip-setup.md
│   └── 03-agent-design.md
│
├── reviews/
│   ├── 01-why-ai-company.review.md
│   ├── 02-paperclip-setup.review.md
│   └── 03-agent-design.review.md
│
└── final/
    ├── 01-why-ai-company.md
    ├── 02-paperclip-setup.md
    └── 03-agent-design.md

CEO의 초기화 책임

CEO는 새 프로젝트를 시작할 때 Researcher에게 위임하기 전에 디렉토리 구조를 먼저 생성해야 한다. 이 단계를 빠뜨리면 Researcher의 첫 번째 저장에서 FileNotFoundError가 발생한다.

# CEO가 프로젝트 시작 시 실행
mkdir -p /app/workspace/blog-personal-ai-company-setup/{research,drafts,reviews,final}

트러블슈팅: 경로 관련 자주 만나는 오류

오류 1: 파일 없음 (상대경로 저장 불일치)

증상

FileNotFoundError: /app/workspace/blog-project/research/output.md not found

Creator가 Researcher 산출물을 찾지 못한다. Researcher가 완료 보고를 했는데도 파일이 없다.

원인
Researcher가 ./workspace/research/output.md(상대경로)에 저장했다. Creator는 위임 메시지에 적힌 절대경로 /app/workspace/blog-project/research/output.md를 읽으려 하지만 해당 위치에 파일이 없다.

해결책
Researcher 시스템 프롬프트의 ## ⚠️ 절대경로 규칙 섹션을 점검한다. 파일 존재 여부는 아래 명령으로 직접 확인한다.

ls /app/workspace/blog-project/research/

오류 2: 프로젝트 디렉토리 없음 (CEO 초기화 누락)

증상

FileNotFoundError: [Errno 2] No such file or directory:
'/app/workspace/new-project/research/output.md'

Researcher가 파일 저장을 시도하지만 디렉토리 자체가 없다.

원인
CEO가 새 프로젝트 시작 시 /app/workspace/{project-name}/ 하위 디렉토리를 생성하지 않았다.

해결책
CEO가 Researcher에게 위임하기 전에 프로젝트 디렉토리 구조를 먼저 생성한다.

mkdir -p /app/workspace/{project-name}/{research,drafts,reviews,final}

오류 3: sandbox 혼동 (성공 보고 후 파일 없음)

증상
Researcher가 "저장 완료"를 보고했다. 에이전트 로그에는 Write 도구 호출이 성공으로 기록되어 있다. 하지만 /app/workspace/project/research/를 확인하면 파일이 없다.

원인
에이전트가 상대경로(./workspace/research/output.md)로 파일을 저장했다. Write 도구 자체는 성공했지만 에이전트의 격리 sandbox에 저장됐다. 격리 sandbox는 공유 경로가 아니므로 다른 에이전트에서 접근할 수 없다.

해결책
에이전트 heartbeat 로그에서 실제 Write 도구 호출 경로를 확인한다. 경로가 /app/workspace/로 시작하지 않으면 절대경로 규칙 위반이다. Paperclip UI → 해당 에이전트 → Instructions 탭에서 절대경로 규칙 섹션을 점검하고 재저장한다.

오류 4: 프로젝트명 불일치

증상
/app/workspace/blog-personal-ai-company/research/에 파일이 있는데 Creator가 /app/workspace/blog-personal-ai-company-setup/research/를 찾는다.

원인
CEO 위임 메시지에 기재한 {project-name}과 에이전트가 실제로 사용한 디렉토리명이 다르다. 오타, 버전 불일치, 또는 에이전트가 임의로 프로젝트명을 변경했을 가능성이 있다.

해결책
CEO가 위임 메시지에서 {project-name}을 명확히 명시한다. 에이전트는 CEO가 지정한 프로젝트명을 임의로 변경하지 않는다.

# 실제 디렉토리 확인
ls /app/workspace/

오류 5: 스킬 파일 읽기 실패

증상
에이전트가 스킬 파일 없이 기본 행동으로 작업을 진행한다. 블로그 문체 규칙이나 코드 스타일 가이드가 무시된다.

원인
스킬 파일 경로가 상대경로이거나 오타가 있다.

해결책
스킬 파일 참조 시 반드시 절대경로를 사용한다.

올바름: /app/skills/blog-writing.md
잘못됨: ./skills/blog-writing.md
잘못됨: skills/blog-writing.md
잘못됨: ../skills/blog-writing.md

마치며: 절대경로 하나로 팀 협업이 성립한다

절대경로 규칙 하나가 5개 에이전트의 협업을 성립시킨다. 어느 한 에이전트가 이 규칙을 어기면 파이프라인 전체가 깨진다. 시스템 프롬프트에 ## ⚠️ 절대경로 규칙 (최우선)을 명시하고 모든 에이전트에 일관되게 적용하면, Researcher의 산출물이 Creator에게, Creator의 초안이 Reviewer에게, Reviewer의 검증본이 Executor에게 정확하게 전달된다.

다음 편에서는 이 파이프라인의 품질 게이트인 Reviewer 에이전트의 검수 기준과 실제 리뷰 산출물 구조를 살펴본다.

Personal AI Company 셋업 ③: 5개 에이전트 설계와 등록

Dannian — Mon, 18 May 2026 21:00:09 +0900

팀 구조 설계: 왜 5명인가

에이전트를 하나로 만들면 간단해 보이지만 실제로는 역효과이다. 단일 에이전트가 조사·생성·검증·실행을 모두 담당하면 시스템 프롬프트가 비대해지고, 한 역할의 실수가 전체 파이프라인에 영향을 준다.

Personal AI Company는 단일 책임 원칙(Single Responsibility)을 에이전트 설계에 적용했다. CEO는 조율만 하고, 나머지 4개가 각 단계를 전담한다. 이렇게 하면 에이전트 교체나 재설계가 쉽고, 각 역할의 품질 기준을 독립적으로 높일 수 있다.

파이프라인 흐름은 다음과 같다: 조사(Researcher) → 생성(Creator) → 검증(Reviewer) → 실행(Executor). CEO는 Board(사용자)의 고수준 지시를 이 4단계로 분해하여 child issue로 위임한다.

각 에이전트 비교표

에이전트	Paperclip role	모델	주요 역할	월 예산
CEO	—	Sonnet 4.6	분석·위임·검수, child issue 생성	$30
Researcher	researcher	Sonnet 4.6	외부 정보 수집, research/ 저장	$20
Creator	engineer	Sonnet 4.6	블로그·코드·SNS 초안 생성	$30
Reviewer	qa	Sonnet 4.6	스킬 기준 검수, 최대 2회 재검토	$15
Executor	devops	Haiku 4.5	승인된 배포·Git 명령 실행	$5

Executor만 Haiku를 사용한다. 파일 복사, API 호출, Git 명령처럼 단순한 실행 작업에 Sonnet을 쓰는 건 과소비이기 때문이다. 설정 파일에도 이 의도가 주석으로 명시되어 있다.

# executor.yaml
name: executor
model: claude-haiku-4-5-20251001  # 단순 실행 작업 — Haiku로 비용 절감
budget_monthly: 5

AGENTS.md로 시스템 프롬프트 관리하기

Paperclip은 에이전트 시스템 프롬프트를 managed bundle 방식으로 관리한다. 실제 저장 위치는 다음과 같다.

/paperclip/instances/default/companies/{companyId}/agents/{agentId}/instructions/AGENTS.md

AGENTS.md는 Claude Code가 대화 시작 시 자동으로 로드하는 특별 파일이다. Paperclip이 이 파일을 에이전트 시스템 프롬프트의 진입점으로 사용한다.

Append 패턴이란 초기 역할 정의 위에 섹션을 점진적으로 추가하는 방식이다. 에이전트를 재시작하지 않아도 지침을 동적으로 수정할 수 있고, 변경 이력도 추적할 수 있다. <- 이런게 AI가 맘대로 작성한 내용이다. 그렇기 때문에 사용자는 모든걸 곧이곧대로 믿지 말고 항상 의심하고 검수해야만 한다. 그냥 단순히 AGENTS.md 파일 내의 내용을 추가하거나 변경 할 때 매번 Agents들을 재시작 할 필요 없다 라고 이해하면 된다.

아래는 Creator의 AGENTS.md에서 절대경로 규칙 섹션을 추가한 예시이다.

## ⚠️ 절대경로 규칙 (최우선)

모든 파일 참조는 호스트와 공유되는 절대경로를 사용한다.

- 스킬 파일: `/app/skills/{name}.md`
- 산출물 저장: `/app/workspace/{project-name}/drafts/`
- Researcher 자료 참조: `/app/workspace/{project-name}/research/`

이 규칙이 없으면 에이전트가 상대경로로 파일을 참조해 호스트 파일시스템과 연결이 끊어진다.

instructionsFilePath 함정 피하기

증상

에이전트가 올바른 역할로 동작하지 않거나, 특정 머신에서만 시스템 프롬프트가 로드된다. Paperclip UI에 경고 메시지가 표시되기도 한다.

Using legacy relative instructionsFilePath;
migrate this agent to a managed or absolute external bundle.

원인

instructionsFilePath는 레거시(deprecated) 필드이다. 상대경로를 사용하면 adapterConfig.cwd(에이전트 작업 디렉토리)를 기준으로 경로를 resolve한다. 환경마다 cwd가 다를 수 있어 경로가 불일치한다.

// agent-instructions.ts (간략화)
function resolveLegacyInstructionsPath(candidatePath: string, config: Record<string, unknown>): string {
  if (path.isAbsolute(candidatePath)) return candidatePath;
  const cwd = asString(config.cwd);
  if (!cwd || !path.isAbsolute(cwd)) {
    throw unprocessable(
      "Legacy relative instructionsFilePath requires adapterConfig.cwd to be set to an absolute path",
    );
  }
  return path.resolve(cwd, candidatePath);
}

해결책

방법	권장 여부
Managed Bundle (Paperclip UI → Instructions 탭 직접 편집)	✅ 권장
`instructionsRootPath`에 절대경로 지정	✅ 허용
`instructionsFilePath`에 절대경로	⚠️ 동작하나 비권장
`instructionsFilePath`에 상대경로	❌ 금지

신규 에이전트는 반드시 managed bundle로 시작하고, 기존 에이전트에 상대경로가 있다면 즉시 마이그레이션해야 한다.

dangerouslySkipPermissions — 보안 트레이드오프

dangerouslySkipPermissions는 claude-local 어댑터의 설정 필드로, 기본값은 true이다.

Claude Code CLI는 파일 쓰기·터미널 실행 등 위험한 작업 전에 사용자 승인 프롬프트를 표시한다. Paperclip heartbeat는 완전 자동화된 헤드리스 실행이므로 사람이 이 프롬프트에 응답할 수 없다. 프롬프트가 대기 상태가 되면 heartbeat가 타임아웃될 때까지 멈추기 때문에, dangerouslySkipPermissions: true는 자동화 실행의 구조적 필요조건이다.

위험 측면은 다음과 같다.

에이전트가 시스템의 임의 파일에 접근하거나 수정할 수 있음
악의적 프롬프트 인젝션 공격 시 완충재 없음
잘못 설계된 에이전트가 의도치 않은 파일을 덮어쓸 수 있음

완화 조치도 함께 작동한다.

예산 강제: 월 예산 초과 시 에이전트 자동 중단
거버넌스: Board가 언제든 에이전트를 pause/terminate 가능
샌드박스 실행: sandbox 환경에서는 --dangerously-skip-permissions 대신 허용 도구 목록(--allowedTools)으로 대체
감사 로그: 모든 도구 호출 기록

// permissions.ts
export function buildClaudeExecutionPermissionArgs(input: {
  dangerouslySkipPermissions: boolean;
  targetIsSandbox: boolean;
}): string[] {
  if (!input.dangerouslySkipPermissions) return [];
  if (input.targetIsSandbox) {
    return ["--allowedTools", SANDBOX_ALLOWED_TOOLS];  // 샌드박스: 목록 제한
  }
  return ["--dangerously-skip-permissions"];  // 로컬: 전체 허용
}

로컬 환경에서 자신이 통제하는 인프라에서 실행하는 경우 합리적인 선택이다. 공용 서버나 신뢰할 수 없는 입력이 있는 환경에서는 반드시 샌드박스 실행을 검토해야 한다.

Paperclip UI에서 에이전트 등록하기

에이전트 등록 절차는 다음 순서로 진행한다.

Paperclip 대시보드 → Agents 탭으로 이동한다.
New Agent 버튼을 클릭하고 이름과 role(researcher, engineer, qa, devops 중 선택)을 입력한다.
Model 필드에서 모델을 선택한다. Executor는 claude-haiku-4-5-20251001, 나머지는 claude-sonnet-4-6을 지정한다.
Budget 필드에 월 예산 한도(USD)를 입력한다.
Instructions 탭으로 이동해 시스템 프롬프트를 편집한다. 여기서 편집한 내용이 managed bundle(AGENTS.md)로 저장된다.
절대경로 규칙(/app/workspace/{project-name}/)을 Instructions 최상단에 명시한다.
Save를 클릭하면 다음 heartbeat부터 새 Instructions가 적용된다.

instructionsFilePath나 instructionsRootPath를 별도로 설정하지 않아도 되며, UI에서 직접 편집하는 managed bundle이 기본값이자 권장 방식이다.

다음 편 예고

4편에서는 CEO가 child issue를 생성하고 blocked 상태를 관리하는 워크플로우 자동화를 다룬다. POST /api/issues/{id}/children 패턴과 tree-hold 메커니즘을 실전 예시로 살펴본다.

Personal AI Company 셋업 ②: Paperclip + Claude Code Max 셋업

Dannian — Mon, 18 May 2026 18:00:59 +0900

들어가며

Personal AI Company 시리즈 1편에서 전체 아키텍처와 개념을 살펴봤다. 2편에서는 Paperclip을 실제로 설치하고 Claude Code Max와 연결하는 구체적인 절차를 다룬다. 이 글을 따라하면 로컬 또는 서버 환경에서 Paperclip API 서버가 실행되고, Claude Code가 에이전트로 동작하는 상태가 된다.

사전 요구사항

필수 항목 확인

아래 항목이 모두 준비되어 있어야 한다.

항목	버전 / 조건
Node.js	20 이상
pnpm	9.15 이상
Claude 구독	Max 플랜 (Claude Code 사용 필수)
운영 체제	macOS, Linux, Windows (WSL2)

Claude Max 구독이 필요한 이유

Paperclip은 Claude Code를 에이전트 런타임으로 사용한다. Claude Code는 Claude Max 플랜 이상에서 높은 사용량 한도로 에이전트 루프 실행이 가능하다. 구독 없이 시작하면 에이전트 실행이 즉시 제한되므로 시작 전에 반드시 확인한다.

Claude Max 구독 가격은 Anthropic 공식 사이트에서 확인한다 (공식 문서 없음, 추가 확인 필요).

Node.js와 pnpm 설치 확인

node --version   # 20.x 이상인지 확인
pnpm --version   # 9.15 이상인지 확인

# pnpm이 설치되어 있지 않다면
npm install -g pnpm

Paperclip 설치

npx 원커맨드 설치 (권장)

가장 빠른 설치 방법이다. 아래 한 줄로 Paperclip 설치와 초기 설정이 완료된다. 내장 PostgreSQL이 자동 생성되어 별도 DB 설정이 불필요하다.

npx paperclipai onboard --yes

이미 설정이 있는 경우 onboard를 재실행해도 기존 설정을 유지한다. 설정 변경이 필요한 경우 paperclipai configure 명령을 사용한다.

bind 모드 선택

--bind 옵션으로 서버의 접근 범위를 설정한다. 처음부터 자신의 용도에 맞는 모드를 선택하는 것이 중요하다.

모드	옵션	접근 범위	적합한 상황
로컬 (기본)	옵션 생략	localhost만	개발·테스트
LAN	`--bind lan`	같은 Wi-Fi 내 기기	팀 내부 공유
Tailscale	`--bind tailnet`	Tailscale 망 전체	원격·스마트폰 접근

# LAN 접근 허용 (같은 네트워크의 다른 기기에서 접근)
npx paperclipai onboard --yes --bind lan

# Tailscale 망 내 접근 (원격 접근, 스마트폰 관리용)
npx paperclipai onboard --yes --bind tailnet

수동 설치 (개발자용)

소스 코드를 직접 수정하거나 커스텀 환경을 구성할 때 사용한다.

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

서버가 시작되면 API 서버는 http://localhost:3100에서 동작한다.

환경변수 설정

수동 설치의 경우 또는 기존 설정을 수정할 때 .env 파일을 직접 편집한다.

cp .env.example .env

주요 환경변수는 다음과 같다.

# PostgreSQL 연결 문자열
DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip

# API 서버 포트 (기본: 3100)
PORT=3100

# UI 서빙 여부 (별도 프론트엔드 서버 사용 시 false)
SERVE_UI=false

# 인증 시크릿 키 ⚠️ 프로덕션에서 반드시 변경
BETTER_AUTH_SECRET=paperclip-dev-secret

BETTER_AUTH_SECRET 설정

BETTER_AUTH_SECRET은 세션 인증에 사용하는 핵심 보안 키다. 기본값 paperclip-dev-secret은 개발 전용이며, 외부 접근이 가능한 환경에서는 반드시 강력한 난수로 교체해야 한다.

# macOS / Linux
openssl rand -base64 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

생성된 값을 .env 파일의 BETTER_AUTH_SECRET에 입력한다. 이 값이 유출되면 세션 위조가 가능하므로 Git에 커밋하지 않도록 .gitignore에 .env가 포함되어 있는지 반드시 확인한다. 값을 변경하면 모든 활성 세션이 무효화된다.

Claude CLI 설치 및 인증

Claude CLI 설치

npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

OAuth 인증 흐름

# Claude CLI 로그인 (브라우저 OAuth 팝업)
claude auth login

위 명령을 실행하면 브라우저가 열리고 Anthropic 계정 로그인 페이지로 이동한다. Claude Max 플랜이 연결된 계정으로 로그인한다. 인증이 완료되면 credentials가 ~/.claude/ 디렉토리에 저장된다.

# 인증 상태 확인
claude auth status

컨테이너 환경에서 credentials 전달

Docker 등 컨테이너 환경에서는 호스트의 ~/.claude/ 디렉토리를 컨테이너 내부에 전달해야 한다.

아래 내용은 공식 README에 Docker 가이드가 없으므로, 실제 운영 환경에서 관찰된 패턴 기반이다 (공식 문서 없음, 추가 확인 필요).

방법 1: Volume 마운트 (권장)

# docker-compose.yml
services:
  paperclip:
    volumes:
      - ~/.claude:/root/.claude:ro  # 읽기 전용 마운트

방법 2: 직접 복사

# 호스트에서 컨테이너로 복사
docker cp ~/.claude/. <container_id>:/root/.claude/

# 또는 컨테이너 내부에서 직접 인증
docker exec -it <container_id> claude auth login

트러블슈팅

T1. Node.js 버전 오류로 설치 실패

항목	내용
증상	`Error: The engine "node" is incompatible with this module` 오류
원인	Node.js 버전이 20 미만
해결책	`nvm install 20 && nvm use 20` 실행 또는 공식 Node.js 사이트에서 최신 LTS를 설치한다

T2. BETTER_AUTH_SECRET 미설정으로 인증 실패

항목	내용
증상	로그인 시도 시 세션이 즉시 만료되거나 "Invalid secret" 오류가 발생한다
원인	`.env`에 `BETTER_AUTH_SECRET`이 없거나 기본값(`paperclip-dev-secret`) 상태로 프로덕션 모드 실행
해결책	`openssl rand -base64 32`로 새 시크릿 생성 후 `.env`에 입력하고 서버를 재시작한다

T3. Claude 인증 후에도 에이전트가 "인증 오류" 반환

항목	내용
증상	`claude auth status`는 정상인데, Paperclip 에이전트 실행 시 "Authentication required" 오류
원인	컨테이너·격리 환경에서 `~/.claude` credentials를 찾지 못함
해결책	호스트의 `~/.claude`를 컨테이너 내부로 마운트하거나, 컨테이너 내부에서 직접 `claude auth login`을 실행한다

T4. 포트 3100 충돌로 서버 시작 실패

항목	내용
증상	`Error: listen EADDRINUSE: address already in use :::3100`
원인	다른 프로세스가 이미 3100 포트를 사용 중
해결책	`.env`에서 `PORT=3101`(또는 다른 빈 포트)로 변경 후 재시작. `lsof -i :3100`으로 충돌 프로세스를 먼저 확인한다

T5. Tailscale bind 모드에서 외부 접근 불가

항목	내용
증상	`--bind tailnet`으로 시작했는데 외부 기기에서 대시보드에 접근할 수 없다
원인	Tailscale이 설치되어 있지 않거나 호스트가 Tailscale 망에 미연결
해결책	Tailscale 설치 및 `tailscale up`으로 로그인 후 Paperclip을 재시작한다. 접근 시 Tailscale IP를 사용한다

다음 편 예고

3편에서는 Paperclip 위에서 동작하는 첫 에이전트를 직접 정의하고, CEO-Researcher-Creator 역할 분리 구조를 실제로 구성하는 방법을 다룬다.

Personal AI Company 셋업 ①: 왜 1인 AI 회사인가

Dannian — Mon, 18 May 2026 11:56:19 +0900

AI 에이전트를 여러 개 동시에 운영하다 보면 터미널 탭이 20개를 넘어가고, 어느 에이전트가 무엇을 하고 있는지 파악하기 어려워진다. 1인 AI 회사(Personal AI Company)는 이 문제를 "에이전트를 도구로 쓰지 말고 회사처럼 운영한다"는 관점으로 해결한다. Paperclip은 그 운영 인프라를 제공하는 오픈소스 오케스트레이션 플랫폼이다.

1. 문제: AI 에이전트를 많이 쓸수록 복잡해진다

1-1. 터미널 탭 20개의 혼돈

Claude Code, Cursor, Copilot 등 AI 에이전트를 적극적으로 활용하기 시작하면 곧 관리 문제에 부딪힌다. 에이전트 하나에 터미널 세션 하나씩 붙여두면, 어느 시점부터는 어느 에이전트가 어느 작업을 담당하는지 직접 추적해야 한다. 재시작하면 컨텍스트가 모두 사라지고, 처음부터 다시 설명해야 한다.

1-2. 조율과 비용 통제가 없다

단일 에이전트에게 조사, 생성, 검증, 배포를 모두 맡기면 품질이 들쭉날쭉해진다. pay-as-you-go API 방식이라면 토큰 루프 하나로 예상치 못한 청구서가 날아오기도 한다. 에이전트가 "왜" 이 작업을 해야 하는지 모르기 때문에 주어진 지시의 경계를 벗어나기도 한다.

핵심 문제는 AI 모델 성능이 아니다. 에이전트를 어떻게 조율하느냐가 핵심이다.

2. 해결책: 직원이 아닌 회사

2-1. Paperclip이란

Paperclip은 AI 에이전트를 회사 수준으로 운영하는 오픈소스 오케스트레이션 플랫폼이다(MIT 라이선스). 공식 문서의 표현을 빌리면 "Claude Code가 직원이라면, Paperclip은 그 회사다." 조직도, 예산, 거버넌스, 티켓 시스템, 목표 계층을 갖추고 있어 에이전트가 항상 자신이 무엇을 왜 해야 하는지 알고 실행한다.

2-2. 핵심 구조

Paperclip은 다음 메커니즘으로 에이전트 혼돈을 해결한다.

티켓 기반 작업 추적: 모든 작업이 이슈로 관리되며 에이전트가 checkout하여 처리한다.
Persistent agent state: Heartbeat(주기적 wakeup) 사이에도 작업 컨텍스트가 유지된다.
목표 계층(Goal Tree): 작업이 상위 목표와 연결되어 에이전트가 "왜"를 항상 파악한다.
에이전트별 예산: 월 예산 초과 시 자동 일시정지로 비용 폭주를 막는다.
Governance with rollback: 승인 게이트와 설정 버전 관리로 변경을 통제한다.

로컬 설치는 Node.js 20+, pnpm 9.15+만 있으면 된다(공식 README 기준).

npx paperclipai onboard --yes

위 명령 한 줄로 로컬 서버와 내장 PostgreSQL이 구동된다.

3. 5개 에이전트 조직도

Personal AI Company의 기본 구성은 5가지 역할로 이루어진다. 각 역할은 독립된 시스템 프롬프트로 정의되며, Paperclip의 Org Chart 기능이 상하 보고 구조를 관리한다.

역할	담당	역할 설명	주요 산출물
CEO	CEO	Board(사용자)로부터 지시를 받아 작업을 분해·위임·검수한다. 직접 산출물을 만들지 않는다.	child issue, 작업 분해
Researcher	Researcher	조사 목표와 범위를 확인하고 정보를 수집·구조화한다.	`/research/*.md`
Creator	Creator	Researcher 자료를 바탕으로 콘텐츠·코드를 생성한다.	`/drafts/*.md`
Reviewer	Reviewer	Creator 산출물을 스킬 파일 기준으로 검증하고 통과/수정 판정을 내린다.	`/reviews/*.md`
Executor	Executor	Board 승인 후 최종 산출물을 외부에 배포한다(블로그 발행, git push 등).	`/final/*.md`

워크플로우 방향은 Board → CEO → Researcher → Creator → Reviewer → Executor 순서다. 각 단계는 child issue로 직렬 위임되며, 이전 단계가 완료되어야 다음 단계가 시작된다. 파일시스템은 역할별 디렉토리로 분리되어 에이전트 간 산출물 충돌을 방지한다.

4. 비용 구조: Claude Max + Paperclip OSS

4-1. Claude Max 구독 정책

Paperclip은 Claude Code를 에이전트 런타임으로 사용한다. 비용은 Anthropic의 Claude Max 구독으로 처리한다(공식 페이지 기준).

플랜	월 구독료	용량
Claude Pro	$20/월	기준
Claude Max (기본)	$100/월	Pro의 5배
Claude Max (고용량)	$200/월	Pro의 20배

4-2. 토큰 추가 과금이 없는 의미

API 키 기반 pay-as-you-go 방식과 달리, Claude Max는 구독 고정비만으로 에이전트를 24시간 운영해도 추가 청구가 없다. 1인 운영자 입장에서 월 비용을 $100~$200로 고정할 수 있다는 것은 비용 예측이 단순해진다는 의미다. Paperclip의 에이전트별 예산 기능과 결합하면 각 에이전트의 사용량을 더 세밀하게 통제할 수 있다.

Paperclip 자체는 MIT 오픈소스이므로 별도 라이선스 비용이 없다.

5. 실전 시나리오

시나리오 A: 블로그 자동화 파이프라인

이 글 자체가 해당 파이프라인으로 작성됐다. (물론 AI가 작성한 모든걸 믿지 않기 때문에 전체 내용을 리뷰 한 상태이다.)

Board가 Paperclip에 이슈 등록: "Personal AI Company 셋업 시리즈 1편 작성"
CEO가 작업을 분해하고 Researcher child issue를 생성한다.
Researcher가 참조 파일을 읽고 리서치 문서를 /research/ 에 저장한다.
Creator가 리서치 자료 기반으로 블로그 초안을 /drafts/ 에 작성한다.
Reviewer가 스킬 파일 기준으로 검수(맞춤법, SEO, 코드 정확성)한다.
Board 승인 후 Executor가 GitHub Pages 또는 Tistory에 발행한다.

시나리오 B: Swift 코드 생성 파이프라인

Board: "VIPER 패턴으로 로그인 화면 구현"
CEO가 Creator에게 직행 위임한다(사전 조사가 불필요한 경우).
Creator가 /app/skills/swift-coding.md 규칙에 따라 SnapKit + async/await 코드를 생성한다.
Reviewer가 컴파일 가능 여부, VIPER 레이어 분리, 네이밍 컨벤션을 검수한다.
Executor가 git commit하고 PR을 생성한다(main 브랜치 push는 Board 승인 필수).

시나리오 C: 정기 리포트 자동화

Paperclip의 Routines(스케줄) 기능을 활용하면 매주 월요일 오전 9시 같은 트리거를 설정할 수 있다. 트리거 시 Paperclip이 자동으로 이슈를 생성하고 에이전트를 깨운다(Heartbeat). Researcher가 지난 주 작업 현황을 수집하고, Creator가 요약 리포트를 작성한 뒤, Executor가 Telegram이나 이메일로 발송한다. 사람의 개입 없이 정기 보고가 자동화된다.

6. 이 시리즈에서 다루는 내용

이 시리즈는 Personal AI Company를 직접 구축하는 과정을 순서대로 기록한다.

1편 (이 글): Personal AI Company 셋업 ①: 왜 1인 AI 회사인가
2편: Personal AI Company 셋업 ②: Paperclip + Claude Code Max 셋업
3편: Personal AI Company 셋업 ③: 5개 에이전트 설계와 등록
4편: Personal AI Company 셋업 ④: Path B — 에이전트 간 파일 공유의 해법
5편: Personal AI Company 셋업 ⑤: 자동 wakeup 패턴으로 에이전트 파이프라인 직렬화하기
6편: Personal AI Company 셋업 ⑥: Telegram bridge로 어디서든 에이전트 제어하기
7편: Personal AI Company 셋업 ⑦: 개발자 메모 — 자잘한 함정들

다음 편 예고: 2편에서는 npx paperclipai onboard --yes 한 줄부터 시작해 Org Chart와 5개 에이전트를 실제로 등록하는 과정을 다룬다.

[Codewars] [7Kyu] V A P O R C O D E

Dannian — Sat, 30 Nov 2024 16:07:38 +0900

Codewars - Achieve mastery through coding practice and developer mentorship

A coding practice website for all programming levels – Join a community of over 3 million developers and improve your coding skills in over 55 programming languages!

www.codewars.com

이번 문제는 받은 문자열을 특정 조건에 맞게 변환해서 반환하는 문제입니다.

조건은 다음과 같습니다.

1. 받은 문자열의 각 문자를 대문자로 변환

2. 각 문자 사이 간격 스페이스2개로 구분

3. 원 문자의 간격은 무시

func vaporcode(_ str: String) -> String {
    var strArr = str.compactMap({ $0.uppercased() }) // split(separator: "")
    strArr.removeAll(where: { $0 == " " })
    let returnValue = strArr.joined(separator: "  ")
    return returnValue
}

이 부분은 어려울게 딱히 없습니다.

해당 조건대로 사용해주면 되고, 간략하게 적느냐 정도의 차이만 있네요.

[Codewars] [5Kyu] Consecutive k-Primes

Dannian — Sat, 30 Nov 2024 15:40:41 +0900

Codewars - Achieve mastery through coding practice and developer mentorship

A coding practice website for all programming levels – Join a community of over 3 million developers and improve your coding skills in over 55 programming languages!

www.codewars.com

이번 문제는 소인수분해를 해서 나온 소수들의 갯수를 확인하고, k 값과 동일한 소수의 갯수가 연속되는 횟수에 대해서 구하는 문제입니다.

1. Swift

1-1. 본인의 풀이

소인수분해를 하는 함수를 하나 만들고(primeCountChecker) 해당 함수에서 반환하는 값을 비교해서 k와 동일한 값이 연속해서 반환되는 횟수를 구했습니다.

func consecKprimes(_ k: Int, _ arr: [Int]) -> Int {
    // your code
  var returnValue: Int = 0
  var isContinue: Bool = false
  for element in arr {
    let test = primeCountChecker(element)
    guard test == k else {
      if isContinue { 
        isContinue = false
      }
      continue
    }
    if isContinue == false {
      isContinue = true 
    } else {
      returnValue += 1
    }
    
  }
  return returnValue
}

func primeCountChecker(_ n: Int) -> Int {
  var num = n
  var result: [Int] = []
  var count = 2
  while num != 1 {
    if num % count == 0 {
      num = num / count
      result.append(count)
      count = 2
    } else {
      count += 1
    }
  }
  return result.count
}

primeCountChecker의 동작은 나머지가 0인 값이 나오면 해당 값으로 나눈 결과물을 num에 저장하고, 그 값을 다시 2부터 차례로 나누게 하는 식입니다.

해당 함수에서 result 배열에는 소수들이 들어있습니다.

1-2. Best Solution

Best Practices를 받은 문제풀이입니다.

func consecKprimes(_ k: Int, _ arr: [Int]) -> Int {
    
    func prim(_ n: Int) -> Int {
        var na = n, i = 2, cn = 0
        while na > 1 { while na % i == 0 { cn += 1; na /= i }; i += 1 }
        return cn
    }
    
    var i = 0, cn = 0
    while i < arr.count - 1 {
        if (prim(arr[i]) == k) && (prim(arr[i + 1]) == k)
        {cn += 1}
        i += 1;
    }
    
    return cn
}

동작의 원리 자체는 비슷하지만, 훨씬 간략하게 작성했네요.

알고리즘을 풀다보면 언제나 간략하게 작성하는 사람들을 보게되는데, 항상 신기하게 느껴집니다..

[Codewars] [8Kyu] Convert a String to a Number!

Dannian — Sat, 30 Nov 2024 15:00:45 +0900

Codewars - Achieve mastery through coding practice and developer mentorship

A coding practice website for all programming levels – Join a community of over 3 million developers and improve your coding skills in over 55 programming languages!

www.codewars.com

이번 문제는 매우 간단한 String -> Int 변경 관련 문제입니다.

심지어 조건에 적혀있는대로면 String은 무조건 들어오고, 그 값 또한 무조건 Int라고 하네요.

func stringToNumber(_ string:String) -> Int {
  return Int(string)!
}

이번 문제는 해설도 필요없지만, 변환하는 방법들을 적어보기 위해서 갖고왔습니다.

String에서 Int로 변환할 때는 해당 String(string으로 명명) 값이 정확히 정수로 들어온다는 조건 하에 다음과 같이 사용할 수 있습니다.

let returnValue = Int(string) // optional Int value

Int의 생성자 중 String을 바로 받는게 있어서 가능한데요, 문서에서 관련 내용을 찾아보겠습니다.

https://developer.apple.com/documentation/swift/int#Converting-Strings

내용에 따르면 string으로 받은 값을 optional Int로 반환해주는 생성자이네요.

생각보다 이런 Convert관련된 함수는 잘 되어있는 편입니다.

이런 optional return value들은 optional이 아닌 변수에 할당할 수 없습니다. 별다른 조치를 취하지 않으면 다음과 같은 에러가 발생하겠죠.

1. 기본값을 ?? 통해서 지정하거나

let returnValue = Int(string) ?? 0 // not optional Int value

2. !를 통해서 force-unwrap을 해주거나.

let returnValue = Int(string)! // optional Int value

당연히 2번 값의 경우는 강제종료가 일어날 수 있으니 주의해서 사용하셔야 합니다.

하지만 확실하게 변환에 문제가 없다 할 때는 사용할 수 있겠죠.

또 다른 방법은 다음의 방식이 있습니다.

let returnIntValue = (string as NSString).integerValue

아마 Objective-C 또는 초기 Swift를 사용하던 분들이라면 익숙할 NSString에 선언 되어있는 integerValue를 통해서 Int 값을 불러오는 것입니다. 이경우는 요즘은 사용하는 경우가 없을 것 같지만, 만에 하나 NSString을 다루는 경우에는 이런 방법도 있다 정도로 알고 계시면 될 것 같네요.

Dannian's Warehouse

[회고] 1주차 회고 (2026.07.20 ~ 07.24)

1주차 회고 (2026.07.20 ~ 07.24)

1. 이번 주 커리큘럼

2. 트렌드로 알게 된 것

3. 내가 한 것 (산출물)

4. KPT 회고

Keep — 잘했고 계속할 것

Problem — 어려웠거나 아쉬운 것

Try — 다음에 시도할 것

5. 막혔던 것 & 해결

6. 다음 주 목표

7. 한 줄 정리

[파이썬 기초 1편] 변수와 문자열 — 에러를 일부러 내면서 배운 것들

[파이썬 기초 1편] 변수와 문자열 — 에러를 일부러 내면서 배운 것들

들어가며

1. 변수

변수는 결국 "이름표"

규칙 1. 대소문자를 구분한다

규칙 2. 특수문자와 숫자로 시작하는 이름은 안 된다

규칙 3. ⚠️ 예약어를 변수로 쓰면 큰일 난다

규칙 4. ⚠️ 주피터에서는 "셀 실행 순서"가 곧 코드 순서다

2. 숫자형

정수와 실수

큰 숫자는 밑줄로 끊어 읽자

지수 표현은 결과가 float이다

정수 + 실수 = 실수

산술 연산 7종

복합 연산자

예제 1. 페이지네이션 — //와 %를 같이 쓰는 대표 사례

예제 2. 홀짝 판별

3. ⭐ 문자열

따옴표 안에 따옴표 넣기

줄바꿈과 여러 줄 문자열

문자열 연산 — 덧셈과 곱셈

길이 재기 — 눈에 안 보이는 공백을 찾는 법

인덱싱 — 앞에서 세기, 뒤에서 세기

슬라이싱 — [시작:끝], 끝은 포함 안 됨

예제. 주민번호 마스킹

⭐ f-string — 문자열 포매팅

4. 문자열 메서드 — 데이터 전처리의 도구들

⭐ split() — 문자열 쪼개기

예제. 파일 확장자 분리

replace() — 문자열 바꾸기

실전. 뒤죽박죽 성별 데이터 정리

실전. 리뷰에서 노이즈 제거

lower() / upper() — 대소문자 통일

strip() / lstrip() / rstrip() — 공백 제거

count() — 개수 세기

예제. 리뷰 키워드 빈도

1편 정리

오늘의 함정 4선

손에 익혀야 할 것

Personal AI Company 셋업 ⑤: 자동 wakeup 패턴으로 에이전트 파이프라인 직렬화하기

왜 자동 wakeup이 필요한가

children API가 자동 wakeup의 열쇠다

tree-hold 패턴: blocked + tree-hold는 한 쌍이다

직렬 처리 강제 패턴

동시에 만들면 생기는 문제

올바른 직렬 처리 흐름

CEO 관점 전체 시퀀스

이 시리즈 자체가 작동 증거다

에이전트가 스스로 blocked를 선택하는 이유

트러블슈팅: wakeup 실패 시나리오 3가지

시나리오 1: child를 일반 API로 만든 경우

시나리오 2: blocked 처리를 잊은 경우

시나리오 3: tree-hold 해제 후에도 wakeup이 오지 않는 경우

패턴 체크리스트

다음 편 예고

# Personal AI Company 셋업 ④: Path B — 에이전트 간 파일 공유의 해법

문제 인식: 에이전트는 왜 서로의 파일을 못 찾는가

per-agent sandbox의 구조

상대경로가 실패하는 두 가지 경우

Path B: 공유 워크스페이스 개념

host bind-mount란 무엇인가

/app/workspace/가 공유 채널이 되는 이유

Path A(sandbox) vs Path B(공유) 비교

절대경로 규칙: 5개 에이전트의 공통 약속

CEO가 정의하는 {project-name}

역할별 읽기/쓰기 경로 매핑

예제 1. 페이지네이션 — `//`와 `%`를 같이 쓰는 대표 사례

슬라이싱 — `[시작:끝]`, 끝은 포함 안 됨