Graph 공부하는 학생

[DE] 데이터엔지니어 시리즈 준비

graph-dev — Thu, 27 Nov 2025 11:13:59 +0900

앞으로 어떤 글을 작성할지 고민하다가, 데이터엔지니어 시리즈에 대해 정리해서 실력을 쌓아보려고 합니다.

여러 종류가 있지만, 일단 JD를 살펴보면서 사람들의 관심을 가질 만한 도구로 시작해보려고 합니다. 요새 너무 급변하는 사회라, 관련 기술에 적절하게 대응해야 관심을 끌고, 그것을 위해 더 속도를 내야하는 상황입니다.

데이터 엔지니어 도구: Batch 작업용 도구부터 시작

보통 데이터엔지니어를 한다고 하면, 실시간(Realtime)이나 배치(Batch)를 골라서 성장합니다. 마치 전직하는 게임 캐릭터같죠.

만화로 그려보았습니다

일단 Realtime streaming은 장기적으로 보기로 했고, 지금 관심있는 부분은 Batch를 위한 도구들입니다.

앞으로 이 Batch와 관련하여 공부한 내용을 블로그로 정리할 예정입니다.

작성할 순서는 다음과 같습니다.

Airflow
Spark
PostgreSQL
fastAPI
Hadoop ecosystem

이 다섯 가지를 돌아가면서 정리해보겠습니다. 강의 내용을 정리해보거나 공식 문서를 기반으로 간단한 토이 프로젝트를 수행하면서 만들어볼 예정입니다. 궁극적으로는 이 네가지 도구(Hadoop 제외)를 기반으로 하나의 구조도를 만들고, 하나의 파이프라인을 만들어 배포까지 진행해보는 것입니다.

Airflow

에어플로우는 워크플로우를 DAG(Directed Acyclic Graph) 형태로 정의하고 예약하며 모니터링할 수 있게 해주는 플랫폼입니다.

관련해서 커뮤니티가 매우 발전해있고, 한국 사용자 모임이 잘 되어 있으니, 궁금한 것은 많이 물어볼 수 있어 좋습니다.

* 글로벌 홈페이지

https://airflow.apache.org

Home

Platform created by the community to programmatically author, schedule and monitor workflows.

airflow.apache.org

* 한국 사용자 포럼 https://www.airflow-kr.org

Spark

Spark는 대규모 데이터를 인메모리 방식으로 빠르게 처리할 수 있게 설계된 분산 컴퓨팅 시스템입니다. 빅데이터 다루는 도구이고, PySpark로 정리해보려고 합니다. Python이 주력 언어가 되니까, 이렇게 접근하는게 가장 좋겠다고 생각했습니다. 참고로, Spark 한국 사용자 모임은 Databricks 모임으로 통합된 느낌입니다. 데이터브릭스와 함께 가져가봐야겠네요.

* Spark 한국 사용자 모임 https://www.facebook.com/groups/sparkkoreauser/?locale=ko_KR

PostgreSQL

Postgresql은 신뢰성, 기능 확장성, 표준 준수를 잘 해놓은 오픈 소스 관계형 데이터베이스 관리 시스템(RDBMS)입니다. 즉, 대표적인 오픈소스 데이터베이스입니다. 정리해두어 절때 나쁠 것이 없고, 기업 쿼리 테스트에도 활용할 수 있어 열심히 정리해두면 분명히 도움이 될 것이라 생각합니다. 이 쿼리 테스트는 데이터 분석가 기준으로 많이 보는 모양이네요.

https://www.postgresql.org

PostgreSQL

The world's most advanced open source database.

www.postgresql.org

* 한국 사용자 모임 https://www.facebook.com/groups/postgres.kr/?locale=ko_KR

매년 아래처럼 pgday를 열기도 합니다.

https://pgday.flask.moe

pgday.Seoul 2025 - PostgreSQL 한국 사용자 모임

PostgreSQL 한국 사용자 모임 PostgreSQL을 사랑하는 개발자, 운영자들이 모여 지식과 경험을 공유하는 커뮤니티입니다 10 번째 행사 8 세션 ∞ 열정

pgday.flask.moe

fastAPI

fastAPI는 파이썬 타입 힌트에 기반하며 고성능을 제공하는 API를 구축하기 위한 현대적인 웹 프레임워크입니다. 이 fastAPI는 데이터엔지니어 분과 논의해보니 규모가 작은 기업은 대부분 백엔드 엔지니어, 개발자가 데이터 엔지니어 역할을 병행하는 경우가 많기 때문에 다룰 수 있어야 한다는 의견을 받았습니다.

주로 백엔드 개발자가 사용하는데, 그럼에도 python을 활용하고 사용법도 어렵지 않습니다. Django보다 속도도 빠르니, 정말 빠르게 익혀보려고 합니다.

https://fastapi.tiangolo.com/ko/

FastAPI

FastAPI framework, high performance, easy to learn, fast to code, ready for production

fastapi.tiangolo.com

Hadoop Ecosystem

하둡은 대규모 데이터 세트를 분산하여 저장하고 처리할 수 있게 해주는 오픈 소스 소프트웨어 프레임워크 및 관련 프로젝트들의 집합입니다. 역사가 깊은 빅데이터 분산 처리 플랫폼입니다. Spark로 많이 대체하고 있지만, 일부 기업은 여전히 JD에 언급하고 있어서, 개념은 확실히 알아두어야할 것 같습니다. 애초에 하둡 생태계 안에 Spark가 있었으니까요. 그래서 데이터브릭스가 하둡, 스파크 키워드로 검색할 때 자주 보이나 싶습니다.

문제는 하둡은 너무 범위가 넓고, 내부적인 도구도 여러개 입니다. 그래서 개념만 익혀보고, 필요하다면 자주 사용하는 일부 도구만 익힐 예정입니다.

https://hadoop.apache.org

Apache Hadoop

<!--- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or a

hadoop.apache.org

https://www.databricks.com/glossary/hadoop-ecosystem

What is a Hadoop Ecosystem?

Apache Hadoop ecosystem refers to the various components of the Hadoop software library; it includes open source projects and a complete range of tools.

www.databricks.com

그 이후에 내년 상반기 중에는 DBT, OpenSearch, Elastic Search를 함께 다뤄보고, 이 Search 시리즈는 기존 DB 포지션을 대체할 수 있을지 테스트 해보려고 합니다.

배포를 생각하면, 나중에 ArgoCD 혹은 컨테이너(Docker), Kubernetes도 함께 고려해봐야겠지만, 기본기에 충실하게 공부하고 나서 응용할 때 곁가지를 쳐보는 게 효과가 좋았습니다.

지금은 하나씩 뿌수는 단계라기보다는 돌아가면서 맛을 보고, 익숙해지는 시간으로 가져가보겠습니다. 기술 스택을 돌려가면서 쌓아보죠!

2026년 힘내보겠습니다!

[Ncloud] NCP Security 시험 후기

graph-dev — Wed, 26 Nov 2025 17:49:44 +0900

네이버클라우드 보안 시험(NCP-Security) 후기를 남겨봅니다. 이 자격증 시험은 공식 홈페이지에 따르면 다음과 같이 구성됩니다. 230번 단일 과목으로 작성 시점 기준, 응시료 5만 5천원이 필요합니다.

자격증 이름은 "NAVER Cloud Platform Certified Professional Security" 입니다. 참고로 자격증 취득시 아래와 같이 발급이 됩니다.

이제 어떻게 준비했는지 말씀드리겠습니다. 참고로, 저는 공인 교육을 수강하고 시험을 준비했습니다. 공인 교육은 유료로 20만원이 필요합니다.

공인 교육 없이 응시하시는 분을 위해 두 가지 방향으로 정리해보겠습니다.

공인 교육 (유료)

아래 네이버클라우드 교육 포털에서, 공인 교육을 눌러주고, 다음 버튼을 눌러 결제 후 공인 교육 신청을 완료합니다. 이후에 안내된 곳에서 교육을 수강합니다.

https://edu.ncloud.com/schedule/calendar

EDU PORTAL - NAVER CLOUD PLATFORM

Improve your company’s operational competitiveness with a simple and fast workflow.

edu.ncloud.com

오프라인 공인 교육 1일짜리를 제공해줍니다. 신청해서 들어보시면 보다 효과적으로 대비가 가능한 시험입니다. 자료에서 제공하는 여러 꿀팁 내용과 강사님이 중요하다고 강조한 사항 위주로 대비하면 좋은 결과를 거둘 수 있습니다.

독학

공인 교육 없이 대비를 하려면, 네이버클라우드 보안 상품 위주로 공식 문서를 정독하시기를 권유드립니다. 보안 상품은 공식 홈페이지에서 카테고리로 찾아볼 수 있습니다.

https://www.ncloud.com

NAVER CLOUD PLATFORM

cloud computing services for corporations, IaaS, PaaS, SaaS, with Global region and Security Technology Certification

www.ncloud.com

1. 네이버클라우드 보안 상품 공식문서 정독

네이버클라우드 보안 상품은 Ncloud 홈페이지 > 서비스 > Security 카테고리에서 확인할 수 있습니다.

이렇게 많은 상품이 있는데, 실습은 어렵고, 공식 문서 위주로 기능을 꼼꼼히 살펴보기를 권장드립니다.

제가 봤을 때 기준으로 꽤 상세히 물어본다고 생각하는 부분은 다음과 같습니다.

① Checker 시리즈(Web Security Checker, System Security Checker)

② Safer 시리즈(App Safer, File Safer)

③ SSL VPN

예를 들어 Checker 상품군이라면, 상세 기능 탭에 있는 정보를 한번 훑어보고, 진단 항목 부분을 암기해두면 효과적입니다.

https://www.ncloud.com/product/security/webSecurityChecker#detail

그 외에 거의 다루지 않는 상품은 Secret Manager 였습니다.

추가로 아래 블로그 내용을 한번 읽어보시면 도움이 됩니다. 저도 도움을 많이 받았습니다.

https://brunch.co.kr/@topasvga/5319

5-3. 네이버 클라우드 보안 시험 응시 방법 안내

1 네이버 클라우드 시험응시. 1과목 5만 5천원. # 추가 자료 1 기술자격증 종류와 신청하기 https://edu.ncloud.com/certi/rating 2 시험 신청 상세 가이드 다운로드 https://kr.object.ncloudstorage.com/technical.certi/%5BN

brunch.co.kr

2. 일반 보안 상식

잘 알려진 포트번호

먼저, 주요 포트번호와 각 포트번호에 사용되는 프로토콜 위주로 암기 해주시면 됩니다. 과거에 정보처리기사/정보보안 공부하실 때 배운 "잘 알려진 포트(Well-Known Ports, 0-1023번)"를 잘 숙지해가시면 좋습니다.

특히, 보안에 관한 포트번호는 프로토콜(TCP, UDP)를 잘 구분해주시는 것을 중요하게 봅니다. TCP에서만 사용하는지, UDP에서만 사용하는지, 두가지 모두 사용할 수 있는지를 명확히 구분해주세요.

아래 위키피디아 문서를 정독/암기해주시면 충분합니다.

https://ko.wikipedia.org/wiki/TCP/UDP의_포트_목록

TCP/UDP의 포트 목록 - 위키백과, 우리 모두의 백과사전

위키백과, 우리 모두의 백과사전. 잘 알려진 포트(well-known port)는 특정한 쓰임새를 위해서 IANA에서 할당한 TCP 및 UDP 포트 번호의 일부이다. 일반적으로 포트 번호는 다음과 같이 세 가지로 나눌

ko.wikipedia.org

리눅스 서버 정보 명령어

위에서 포트 번호를 익혔다는 것은, 포트 정보를 알아내야 할 수도 있습니다. 이 포트 스캔은 보안 시험이지만, 해킹에도 사용할 수 있는 명령어입니다. 이런 명령어도 알아둬야합니다. 최소한 서버 정보(도메인 정보)를 찾아내는 명령어, 포트 스캔하는 명령어 정도는 알아둬야 합니다.

예를 들어, nmap이라는 포트 스캔 명령어가 있을 때, 포트 정보를 활용해서 해당 서버를 공격하는 수단이 되기도 합니다. 이렇게 모두 보안과 해킹 모두 활용할 수 있는 명령어를 간단히 정리해두시는 것을 추천드립니다.

https://velog.io/@dhlife09/nmap-사용법-정리

nmap 사용법 정리 및 실습

nmap

velog.io

리눅스 권한 부여

1. 일반 권한

권한은 보안에 있어 상당히 중요합니다. 관련하여 명령어를 암기해두세요. 아래 블로그 내용을 참고하면 좋습니다.

https://inpa.tistory.com/entry/LINUX- -파일-권한-소유권허가권- -정리

최소한 r, w, x가 각각 십진수 숫자로 표기하고, 소유자, 그룹, 다른 사용자일때 함께 권한을 변경하려면 어떤 명령어를 사용하는지는 확인합니다. 예를 들어, 디렉토리에서 ls -al 명령어를 입력했을 때, 특정 디렉토리의 권한이 drwxrwxr-x 이렇게 나오면, 첫번째 d는 디렉토리이고, 그 다음으로 나오는 각 2-4, 5-7, 8-10번째 자리값을 chmod 명령어로 입력할 때, chmod 775 이렇게 표현된다는 것은 알아두는 게 좋습니다. 위 블로그에서 자세히 나와있으니 참고하시면 좋겠습니다.

2. 특수 권한

이 권한에서 다음으로 헷갈릴 만한 내용은 Sticky Bit 스티키 비트와 Set User ID(SUID), Set Group ID(SGID) 정도입니다. 이 내용도 잘 정리해두면 도움이 많이 됩니다.

예를 들어 보겠습니다. 아래와 같은 문자열이 나타날 경우를 가정합니다. 스티키 비트는 t로 나타내고, 1을 맨 앞자리에 붙입니다. 특수 권한은 무조건 맨 앞에 붙는다고 생각하고 계산하면 됩니다. 주로 디렉토리인 경우 사용합니다. 스티키 비트는 리눅스 파일에서는 무시된다고 하는데, 이런 경우는 제외해주고 생각합니다.

https://www.youtube.com/watch?v=uMXHux5aTDY&t=14s

권한 종류	기호	위치	숫자값	설명
SetUID (SUID)	s 또는 S	소유자(User)의 x 자리	4	실행 시 파일 소유자의 권한으로 실행
SetGID (SGID)	s 또는 S	그룹(Group)의 x 자리	2	실행 시 그룹의 권한을 상속받음
Sticky Bit	t 또는 T	기타(Other)의 x 자리	1	누구나 쓸 수 있지만, 삭제는 소유자만 가능

참고로 대문자(S, T) 기호는 일단 고려하지 않았습니다. 너무 깊이 들어가네요!

이제 예시로 살펴보겠습니다.

가령, drwsr--r-t 이렇게 되어 있으면 s라는 suid(user자리), t는 other에 붙은 스티키 비트입니다. 이런 경우, user 자리의 suid는 소문자 s이므로 4로 계산합니다. t는 other 자리에 있고 1로 계산합니다.

이 두 가지 특수 권한은 서로 더해주면, SUID(4) + Sticky(1) = 5가 되고, 맨 앞자리에 붙입니다. 보통 이러한 특수 권한이 없으면 0745 이런식으로 나오는데, 맨 앞의 0은 생략합니다. 그러면 745 이렇게 나옵니다. 그러나 특수 권한 계산값이 0이 아니라면 표기해줘야합니다.

1) d, s, t를 먼저 빼고, 그 자리에 원래 값으로 대체한 나머지 세자리를 계산합니다.

기존 rwsr--r-t를 rwxr--r-x로 치환하여 계산합니다.

rwxr--r-x 는 user (4+2+1 = 7), group (4+0+0 = 4), other (4+0+1 = 5)으로 계산하므로 745가 됩니다.

2) 특수 권한인 s, t를 계산한 값인 5를 맨 앞에 붙입니다. 그러면, 5745가 되는 방식입니다.

다른 예시도 아래 표를 참고해보세요. 응용하여 문제 나오기 좋습니다.

예시 문자열	특수권한 계산 (1자리)	일반권한 계산 (3자리)	최종 숫자
drwxrw-r--	없음 (0)	7 / 6 / 4	764
drwxrwsr-t	SGID(2) + Sticky(1) = 3	7 / 7 / 5	3775
drwsrwsr-t	SUID(4)+SGID(2)+Sticky(1) = 7	7 / 7 / 5	7775

윈도우와 리눅스 보안 체계

윈도우와 리눅스 보안에 관한 경로, 시스템, 방화벽을 간단히 정리해두면 좋습니다. 서로 비교해보는 재미도 있습니다.

https://learn.microsoft.com/ko-kr/windows/security/application-security/application-control/user-account-control/

사용자 계정 컨트롤

UAC(사용자 계정 컨트롤)가 Windows 디바이스에 대한 무단 변경을 방지하는 데 어떻게 도움이 되는지 알아봅니다.

learn.microsoft.com

https://withcoding.com/106

리눅스 su, sudo 명령어 사용법 정리 (root 권한 획득 방법)

리눅스(Linux)에서 특정 명령을 실행하거나 파일에 접근하기 위해서는 루트(root) 권한이 필요합니다. 일반 사용자(유저)가 root 권한을 사용하기 위해서 su, sudo 명령어를 사용합니다. 이 글에서는

withcoding.com

IPTables 명령어

iptables라는 명령어에 대해서도 정리해두면 좋습니다.

https://monkeybusiness.tistory.com/678

[리눅스] iptables 명령어 완벽 가이드 사용법(방화벽 설정)

iptables는 리눅스에서 네트워크 패킷 필터링 및 방화벽 설정을 관리하는 강력한 도구입니다. 이를 통해 트래픽을 제어하거나 특정 패킷을 차단, 허용할 수 있습니다. 패킷 필터링은 보안 정책을

monkeybusiness.tistory.com

예를들면, 아래와 같이 명령어를 작성할 수 있어야 합니다. 객관식이므로, 특정한 요청사항에 대해 작성된 명령어를 구분할 수만 있다면 충분합니다.

# SSH (22번 포트) 허용
iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# HTTP (80번), HTTPS (443번) 허용
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

정리해보겠습니다. 만약 100점을 목표로 하시는 분들이라면, 공인 교육을 꼭 수강하시길 바랍니다. 하지만 합격은 전체 100점 중에서 60점 이상이면 충분하므로, 전략적으로 잘 준비하셔서 취득하시길 권장드립니다.

보안의 중요성이 계속 커지고 있습니다. 기존 Legacy 보안과 네이버클라우드에서 보안 상품을 함께 고려할 수 있는 전문가로 성장하시기를 기대합니다.

[Ncloud] Technical Writer 팀 특강 후기: 신뢰를 주는 기술 글쓰기

graph-dev — Tue, 11 Nov 2025 10:40:36 +0900

글을 잘 쓰는 방법에 대해 늘 고민이던 차에, 좋은 기회를 얻어 네이버클라우드 테크니컬 라이팅 팀 리더분의 특강을 듣게 되었습니다.

정리하여 공유해보겠습니다.

가장 중요한 점은 기술 문서를 쓸 때에는 내 나름대로 작성하는 것이 아니라, 정확한 내용을 담는다는 점입니다.

목차
Introduction
- Technical Writing 정의
- 강의 목표와 기대 효과
Easy to Find: 찾기 쉬운 문서 만들기
- 정보 구조화
- 검색 최적화
Easy to Understand: 이해하기 쉬운 문서 작성
- 사용자 분석
- Plain Language 원칙
- 시각 자료 활용
Easy to Use: 활용하기 쉬운 문서 설계
- 문제 해결을 위한 문서 설계
- 행동 중심의 내용 구성

효과적인 테크니컬 라이팅 원리: 찾기, 이해, 사용

시작은 문학적 글쓰기와 차이로 문을 열었습니다.

문학적 글쓰기 : 표현력, 감성, 아름다움으로 읽는 즐거움을 느끼고, 저자의 개성을 강조합니다.
기술 문서 : 객관적 사실을 명확히 작성하고, 사용자의 작업을 유도합니다. 정확성, 명확성, 구조화 > 문제 해결 > 일관성과 표준화가 되어야 합니다.

테크니컬 라이팅의 3대 원칙

테크니컬 라이팅의 3대 원칙은 "쉽게 찾고, 이해하고, 사용한다." 라는 점을 두고, 하나씩 살펴보겠습니다.

쉽게 찾는다 : Easy to Find

정보 구조화

사용자가 원하는 정보를 빠르게 찾고, 문맥을 이해하기 쉽게 정보를 배열합니다.
분류하고 구조화합니다.

중요한 것부터 보여준다
사용자가 필요로 하는 순서대로 구성한다
기본부터 응용으로 구성한다

Topic 단위의 구성

정보를 구성하는 방법입니다.
토픽 (문서의 의미 단위)을 쪼개어 작성한다.
청크를 의미 단위인 토픽이라고 한다.

기술문서의 토픽 세가지 : Concept Task Reference

컨셉: 이게 무엇인가에 대한 정보를 준다.
Task: 절차, 조작 순서 나타냄. 123… 사용 순서 잘 넣어야 한다.
Reference : 항목, 세부정보, 매개변수, 에러코드 배치 등 테이블 형태로 모아서 한번에 부가정보를 줍니다.

정보 탐색 구조 설계

네비게이션? 검색?
정보 탐색하기 쉽게 하려고 예측한다.
전체 목차를 제공해서, 문서 구조를 한 눈에 바라본다.
브래드 크롬 : 실제 문서의 경로 정보
맨 아래 [이전], [다음] 정보가 어떤지 네비게이션으로 설계한다.
- 블로그는 이 정보가 고정된 경우가 많다.
위키 페이지

검색 최적화 방법 3가지

검색 엔진에 내 문서가 잘 걸리게 해야 한다.

메타데이터 활용
키워드 최적화
태그

* 메타데이터는 사람이 보려는 게 아닙니다.

검색 엔진에게 내 문서가 이렇다고 제공한다. 이런 태그에 매핑되는 검색되게 하는 문서 제공한다.

문서 속성(제목, 설명, 작성자, 서비스명, 버전, 플랫폼 등)

* 키워드 최적화: 일반 사용자 타겟

자연스러운 키워드 반영하고, 동일 개념은 대표 용어 1개만 지정합니다.

즉, 같은 의미는 하나의 용어만 사용합니다. 이게 검색 최적화. 키워드 최적화라고 부르는 것입니다.

태그 관리 전략

사용자 타겟 태그 지정
키워드는 딱 대표 용어 하나만 지정해서 쓴다.
근데 대표 용어만 하면 안걸리자나. 그래서 로그인, Sign in, 인증 등 다 집어넣기.
대신, 동의어/약어도 확장 가능.
주의할 점: 검색엔진은 ‘띄어쓰기, 대소문자’에 민감합니다.

Easy to Understand

독자 분석
일관성 확보의 핵심 - 스타일 가이드
Plain Language 원칙
이해를 돕는 시각 자료 활용

독자 분석

문서를 쓸 때, 독자를 분석하는 게 구조화에서 필요하다. 내용 전개시에도 중요하다.
독자의 배경지식
컨텐츠
어떤 맥락?

사용자 대상별로 설명 방식에 차이를 둡니다.

초급 사용자 : 기본 용어로 쉽게 설명합니다.
중급 사용자 : 너무 자세한 개념 설명보다, 절차 설명을 먼저 합니다.
전문가 : 예외사항, 활용 예제 위주로 꾸미는 것으로도 설명 가능합니다.

목적에 따라서도 구분할 수 있습니다.

네이버클라우드 기술 문서라면, 네이버클라우드 사용자가 이해하기 쉽게 만들어야 합니다.
블로그라면, 내 블로그를 누가 들어와서 볼지를 생각해보고, 블로그 작성 목적을 세웁니다.

일관성 확보의 핵심 - 스타일 가이드

이거는 다수가 함께 작성시 이 스타일 가이드 굉장히 중요합니다. 문서 일관성 통해 가독성, 신뢰도, 이해도 높이는 최소한의 장치로,

용어 일관성, 문법과 포맷의 문체 일관성을 고려합니다.

문서의 일관성 확보하여, 사용자를 고민하지 않게 만들어야 합니다.

패턴 정의

용어, 단어, 날짜표기 > 규칙을 정의한다.

문체 (톤 앤 매너) 통일을 위한 규정을 한다.

기술 글쓰기를 하려면, 가장 기본적인 내용에 충실한다.

토픽 (Topic)

스타일 가이드 - 제목
스타일 가이드 - 도입문

숙지하면 말할 수 있다. 이걸 도입문으로 작성할 수 있다. 기대하는 정보라 생각하고 들어가거나 바로 나아감. 제모과 사용자를 이어준다.

스타일 가이드 - 목록

순서가 없는 목록
순서가 있는 목록
물론 시나리오 같은 흐름은 쓰지만, 순서 기호 일반적으로 쓰지 않는다.

스타일 가이드 - UI 표기 규칙

웹 서비스 사용
UI 원문(실제 화면 텍스트)과의 일치성 유지
중요한거, 계속 화면 UI가 바뀔 수 있다.

일반 텍스트, GUI 텍스트 볼드체 표기하며, 네클가이드에서 볼드체는 GUI만 있다.

어느게 GUI, 버튼인지 바로 확인할 수 있다. [확인], <확인>, 확인 안된다. >> 하나로 통일하시라

네클 예시로 표기한다. 굵은 글씨 쓰고, 각괄호를 사용합니다.

스타일 가이드 - 표

내용 전개시 사용하는 도입글, 순서 목록 등 > 그 다음으로 많이 쓰는 게 “표” 입니다.
표에도 작성할 때, 스타일 가이드에 맞추어 주의해서 작성합니다.

표는 텍스트 공간 제약있습니다. 그래서 명사형으로 쓰는 것을 권유합니다.

조사도 생략, 다듬어서 명사형 쓰는게 문서가 더 깔끔하고, 가독성이 좋아집니다.

또한, 순서가 있어야 합니다.

제목

도입문

조작순서

GUI는 볼드체로 넣어주면, 아주 확연히 다르게 보인다.

* Plain Language 원칙: 간단하고 짧은 문장

Easy to Use

문제 해결을 위한 문서 설계

사용자가 스스로 문제 해결하도록 돕는 구조로, 기능 중심보다 문제 해결 중심으로 작성합니다.

특히, 도입문 만으로 내게 맞는 정보라는 점을 알 수 있어야 합니다.

기술 문서 전반에 걸쳐 문제 해결 목적 의식을 갖추어야합니다. 특히, Troubleshooting, FAQ, Error Message Guide에서 문제 해결 목적에 맞게 작성하는 것이 중요합니다.

문서와 장애를 원인, 실질적인 원인 해결방법, 동일한 레퍼런스 하나 더 제공한다. > 알림 메시지 목록에서도 확인할 수 있다.

에러 해결의 상호 참조 하이퍼링크도 제공한다.

비교: FAQ

일반가이드와 다르게 자주 묶는 질문을 모아서 처리한다. 여기는 아주 자세한 해결 안함. 간단한거 모아서 답변한다.

FAQ는 가이드가 아니다. 혹은 필요시 상호 참조 링크를 보내어 상호 참조 가능하게 해주면 끝이다.

사용자 중심, 행동 중심 문장 설계

사용자가 직접 수행할 수 있는 행동 단위로 단계 제시

조작 지시문(능동문)

조작 결과문(피동문)

숫자는 조작 지시에서 많이 사용한다. 불필요하게 숫자 목록을 쓰지 않습니다.

피동문은 조작 결과 화면을 설명할 때 많이 사용합니다.

ex) 1. 점 목록은 조작 결과문(- 대시)

1. 접속해 주십시오 

2. 로그인 버튼 클릭  + 결과 화면 제시

신뢰를 설계하는 문서 작성 (1)

가장 최신 버전이라는 것을 심리적으로 인지시킵니다.

제품 스펙 정보, 수치, 단위에 오탈자가 있으면 안됩니다. 이런 경우 쓸모있는 정보로 안봅니다.

신뢰를 설계하는 문서 작성 (2)

특정 릴리즈를 한다.

애매한 것을 정확하게 만들어야 한다.

끊김 없는 정보 흐름 설계

내비게이션 요소 설계 원칙을 지킵니다. 특히, 사용자가 노력안해도 자연스럽게 찾게 해야 합니다.

이와 관련된 특성 네가지 기억합니다.

예측 가능성, 일관성, 가시성, 맥락 유지성

예측 가능성
일관성
가시성: 어디든 눈에 띈다
맥락 유지성: 맥락 정보를 어디든 유지하게 만든다.

찾기 쉽게 노출하고, 이해하기, 따라하기 어렵지 않은지, 문제가 해결될 수 있는지를 고민하며 작성합니다.

기술 문서를 사용할 때 주의사항에 대해 깊이 고민할 수 있는 시간이었습니다.

Easy to find, understand, use 원칙에 입각해서, 기술 문서를 작성한다는 점을 기억하고, 블로그 쓸 때도 유용한 정보를 일부 가져와서 적용해보겠습니다.

[Ncloud] Data Stream으로 서버리스 데이터 스트리밍 시작하기

graph-dev — Sat, 1 Nov 2025 21:59:38 +0900

네이버클라우드 로고

Data Stream 서비스 소개

네이버클라우드에 데이터 스트림이라는 서비스가 새롭게 등장했습니다.

이 서비스의 가장 큰 특징은 '서버리스' 입니다. 내가 별도의 서버를 만들지 않아도, 내부적인 서버가 존재하고 있어서 바로 동작한다고 생각하면 편합니다.

정리하면, Data Stream은 서버리스 Kafka 도구라고 이해하면 되겠습니다.

사용 방법도 매우 간단합니다.

Data Stream 서비스 활용

데이터 스트림

0. 대시보드 확인

대시보드

Data Stream 서비스는 별도 신청과정이 없습니다. 토픽을 생성하기 전에는 요금 부과도 되지 않고, 위처럼 대시보드에서 토픽, 파티션, 컨슈머 그룹 수가 0개인 것을 한눈에 확인할 수 있습니다.

사전 준비사항으로, 서브 계정을 만들고, 인증키를 받아두어야 합니다.

서브 계정 (Sub Account)

이 상품(Data Stream)은 메인 계정으로는 토픽에 접근할 수 없게 막아놓았습니다. 그래서 서브 계정을 반드시 만들고, 적절한 권한과 인증키 부여를 해야 작동합니다. 추가로 서브 계정은 무료입니다.

서브 계정에 인증키 부여와 권한을 부여하려면, 메인 계정으로 접근하는 게 가장 편합니다.

VPC > Sub Account > Sub Accounts로 접근해서, "서브 계정 생성"을 진행합니다. 테스트 용으로 만들고, "콘솔 접근" 허용을 해야 합니다. 또한, 보안이 필요하다면, 지정된 IP 대역을 설정해주시면 더 안전하게 활용할 수 있습니다.

대신, 지정한 장소 외 다른 곳에서 서브 계정으로 소스 접근이 안될 수도 있습니다. 테스트할 때는 모든 곳에서 접근 가능하도록 설정하고, 테스트가 성공한 뒤에 변경하는 것을 추천합니다.

서브 계정

위 콘솔 접근과 같은 방식으로, API Gateway 접근도 체크해야만 서브 계정에서 인증키 정보를 만들고, 이를 가져올 수 있습니다. 꼭 선택해주세요.

권한 부여

생성 완료 후, 해당 서브 계정에 권한을 부여해줍니다. 권한은 DATA_STREAM으로 검색해서 나오는 것을 테스트용으로 적용해두겠습니다. 권한 부여는 다음과 같이 진행합니다.

먼저 정책 추가를 누르고, 관리형 정책에서정책명으로 DATA_STREAM을 입력하면 나오는 아래 세가지 정책이 있습니다. 이 중에서 VIEWER를 제외하고 모두 선택해줍니다.

인증키 정보

다음으로, 인증키 정보를 가져오겠습니다. Access Key 탭에서 추가를 눌러줍니다. 해당 서브 계정의 인증키 정보가 나오는데, Access Key id, Secret Key 정보를 메모해두세요.

참고로, Secret Key는 '보기' 버튼을 누르면 확인할 수 있습니다.

토픽 생성

서브 계정으로 접속하면, 콘솔에서 서비스를 눌렀을 때, 다음과 같은 화면이 화면이 나타납니다.

위에서 권한을 부여한 것과 관련된 상품만 선택할 수 있습니다. Data Stream을 누릅니다.

이제 토픽을 생성하면 바로 사용할 수 있습니다. 주의할 점은, 토픽 생성과 동시에 분당 요금이 부과됩니다.

토픽 생성을 누릅니다. 이름은 임의로 graph 라고 지었습니다.

여기서 주의할 점은 토픽 이름에는 특수문자 하이픈(-)만 허용이 되고, 최대 200자만 입력할 수 있다는 것입니다.

토픽이 생성 완료되면, 아래 토픽 이름, 파티션 개수, 보존 기간 등이 적혀있습니다. 파티션 개수는 위에서 지정한 개수로 나오고, 수정할 때는 파티션 수를 증가하는 것만 가능하고, 파티션 수를 줄이는 건 불가능하다는 점을 유념해두세요!

접속 엔드포인트는 여러번 생성해보니 대부분 비슷하게 나옵니다.

토픽 이름, 접속 엔드포인트를 복사해둡니다. 참고로 제 토픽 이름은, tymay-graph 네요.

우측 하단 서비스 상세 보기를 누르고, 데이터 탭 > 파티션 0을 선택하면, 아래와 같이 아직 전송된 데이터가 없는 것을 확인할 수 있습니다.

Producer 테스트

Producer는, Kafka 클라이언트로 메시지를 토픽에 전송하는 방법입니다. 서버리스의 강점이 바로 여기에 있습니다. 모든 인프라가 내장되어 있으니, 제공된 엔드포인트 주소, 토픽 이름, 인증키 정보만 입력하면 바로 이 TCP 엔드포인트를 통해 메시지 전송이 가능합니다.

사전에 필요한 파이썬 라이브러리 kafka-python을 설치합니다.

pip install kafka-python

네이버클라우드 가이드에서 제공한 Python 코드는 다음과 같습니다. 여기서 topic_name은 기재된 대로 tymay-graph로 적었습니다. 본인이 지정한 이름으로 수정해서 topic_name을 입력해주세요. 이 코드는 data_stream.py 라는 파일로 저장합니다.

import ssl  

from kafka import KafkaProducer  
import json  


brokers = "cluster로 시작하는 엔드포인트 주소"  
topic_name = "tymay-graph" # 각자 만든 토픽 이름으로 수정 

username = "ncp_iam_으로 시작하는 서브계정 AccessKey"
password = "ncp_iam_으로 시작하는 서브계정 SecretKey"

security_protocol = 'SASL_SSL'  
sasl_mechanism = 'PLAIN'  

# Create a new context using system defaults, disable all but TLS1.2  
context = ssl.create_default_context()  
context.options &= ssl.OP_NO_TLSv1  
context.options &= ssl.OP_NO_TLSv1_1  

producer = KafkaProducer(bootstrap_servers = brokers,  
                        sasl_plain_username = username,  
                        sasl_plain_password = password,  
                        security_protocol = security_protocol,  
                        ssl_context = context,  
                        sasl_mechanism = sasl_mechanism,  
                        api_version = (0,10),  
                        retries=5)  


partition = 0
key = "key-1"
value_dict = {'key':  key, 'data': "Hello, Kafka!"}  
msg_value_json = json.dumps(value_dict)

producer.send(topic=topic_name,  
            key=bytes(key, 'utf-8'),  
            value=msg_value_json.encode("utf-8"),  
            partition=partition)  

producer.flush()

위 파이썬 코드 파일을 실행합니다.

정상적으로 실행되면, 다음 줄에는 아무것도 뜨지 않아야합니다. 무소식이 희소식이에요.

이제 콘솔에서 확인해보겠습니다. "Hello, Kafka!" 메시지를 확인해야 합니다.

Producer 결과 확인

참고로, 한글로 값을 넣으면 아래처럼 다른 값으로 출력됩니다. 유의해주세요!

한글 출력 결과

다시 확인해보겠습니다.

성공이네요!

"Hello, Kafka!" 메시지를 바로 확인할 수 있습니다. 이렇게 서버리스로, 이미 구축된 내장된 서버에서 작동하므로 아주 간단하게 데이터 스트리밍 기능을 수행할 수 있습니다.

이제 Python기반 Kafka 클라이언트 애플리케이션을 사용하여 Data Stream 서비스에 접속해보고, 메시지를 토픽에 송신했습니다. 메시지를 전달했다고 표현해보겠습니다.

Consumer

다음에서는 Consumer 기능을 사용해, 제공된 TCP 엔드포인트에서 메시지를 꺼내서 출력해보겠습니다. Kafka client는 이미 설치된 것으로 가정하고, 다음 Python 코드를 data_stream_consumer.py로 저장해줍니다.

import ssl  


from kafka import KafkaConsumer  

brokers = "cluster로 시작하는 엔드포인트 주소"  
topic_name = "tymay-graph" # 각자 만든 토픽 이름으로 수정 

username = "ncp_iam_으로 시작하는 서브계정 AccessKey"
password = "ncp_iam_으로 시작하는 서브계정 SecretKey"

security_protocol = 'SASL_SSL'  
sasl_mechanism = 'PLAIN'  


# Create a new context using system defaults, disable all but TLS1.2  
context = ssl.create_default_context()  
context.options &= ssl.OP_NO_TLSv1  
context.options &= ssl.OP_NO_TLSv1_1  

consumer = KafkaConsumer(topic_name, bootstrap_servers = brokers,  
						group_id = "test-consumer-group", # 원하는 컨슈머그룹 이름 지정 
						auto_offset_reset='earliest',  
						sasl_plain_username = username,  
						sasl_plain_password = password,  
						security_protocol = security_protocol,  
						ssl_context = context,  
						sasl_mechanism = sasl_mechanism)  

from datetime import datetime  
for message in consumer:  
	print(f'({datetime.now()}) Topic : {message.topic}, Partition : {message.partition}, \
    		Offset : {message.offset}, Key : {message.key}, value : {message.value}')

실행하게 되면, 다음과 같이 입력한 메시지 혹은 데이터가 출력됩니다. "Hello, Kafka!" 메시지를 찾았습니다.

또한, 콘솔에서는 아래와 같은 빈 화면에서, test-consumer-group 이름으로 된 컨슈머 그룹이 생성되며, 오프셋 개수를 시각적으로 확인할 수 있습니다. 현재 2개가 있다고 표기합니다.

주의 사항

처음 실행할 때, test-consumer-group에서 한번 메시지를 읽고나면, 동일한 코드를 실행했을 때 메시지가 출력되지 않습니다. 이 group_id가 일종의 책갈피가 되며, 이것이 마지막으로 가있는 상태로, 다시 읽지 않습니다.

참고로, auto_offset_reset='earliest' 설정은 "이 그룹이 처음 접속해서 책갈피가 아예 없을 때만 처음(earliest)부터 읽어라"라는 뜻입니다. 여기서 한번 읽었다면, 책갈피가 있으니 이 설정은 무시됩니다.

다시 읽어서 출력을 시키려면, group_id를 None으로 설정해서 실행합니다.

consumer = KafkaConsumer(topic_name, bootstrap_servers = brokers,
                        group_id = None,
                        auto_offset_reset='earliest',
                        ...
                        )

한번 실행하고, ctrl+c 를 눌러서 실행을 종료합니다. 그 뒤에 다시 실행해도 메시지가 잘 출력되는 것을 확인할 수 있습니다.

이제 다시 group_id를 test_consumer_group으로 설정하고 실행합니다.

이렇게 실행 중인 상태에서, producer 코드를 실행해서 메시지를 토픽에 새롭게 전송해보겠습니다. 새로운 터미널로 조작해볼게요.

처음에 만든 data_stream.py 파일에서 아래 'data' 값만 "Hello, DataStream!" 으로 수정합니다.

value_dict = {'key':  key, 'data': "Hello, DataStream!"}

이제 data_stream.py 파일을 실행합니다. 이후, "Hello, DataStream1!", "Hello, DataStream2!"로 수정해서 여러번 실행해주었습니다.

그 결과, 아래 그림처럼 우측 터미널(Producer)에서 실시간으로 전송한 토픽 메시지를 좌측 터미널(Consumer)에서 확인해서 출력하는 것을 확인할 수 있습니다.

결과확인

이제 콘솔 > 데이터 탭에서 실제 토픽으로 전송된 메시지를 확인합니다.

다음으로 콘솔 > 컨슈머 그룹 탭에서는, 현재 오프셋도 2개(0,1)에서 5개(0,1,2,3,4)로 증가한 것을 시각적으로 확인할 수 있습니다.

이렇게 별도의 서버 없이도 DataStream 서비스를 활용해서, 실시간으로 토픽에 메시지를 전송하고, 전송된 메시지를 꺼내어 확인해보는 과정을 수행했습니다.

다음 글에서는 기존 Cloud Data Streaming Service(CDSS)라는 상품과 이 DataStream 상품의 기능을 간단히 비교해보겠습니다.

읽어주셔서 감사합니다.

[AI Engineering] 독후감 - 큐레이션과 피드백

graph-dev — Wed, 22 Oct 2025 09:50:26 +0900

AI Engineering 독후감

AI 엔지니어링 도서를 좋은 기회로 얻어서, 책을 읽어보고 후기를 남깁니다.

이 책이 다루는 범위가 제 기준으로는 매우 방대한 편이었습니다. AI 엔지니어링 하나에 AI 모델, 파운데이션 모델, 평가 방법론, 프롬프트 엔지니어링, RAG, 에이전트, 데이터셋 엔지니어링, 추론과 최적화, 아키텍처 및 피드백 등 다양한 내용을 다루고 있었습니다. 한번 읽는다고 모두 소화하기 어려울 수준이었습니다.

어제는 벡터 검색 알고리즘을 보고, 오늘은 데이터셋 큐레이션을 보는 다양한 콘텐츠로 하루하루 즐겁습니다.

일종의 카탈로그 같은 느낌을 받았습니다. 다양하고도 필요한 콘텐츠를 눌러 담은 햄버거나 샌드위치 느낌이 들었습니다. 그래서 더 좋은 것은, 듣기만하고 명확히 몰랐던 "용어"를 조금 더 알아갈 수 있었습니다.

제가 주목한 부분은 데이터셋 큐레이션과 사용자 피드백입니다. 이 내용을 중점적으로 파고 들어가겠습니다.

데이터셋 큐레이션

그 중에서 데이터셋을 생성하고, 큐레이션하는 과정 부분에 더 주목했습니다.

"큐레이션" :
양질의 정보를 선별하고 분류해 특별한 의미를 더해 제공하는 행위로,
정보의 홍수 속에서 필요한 것을 찾기 쉽게 만듭니다.

데이터를 생성하는 과정은 자동화하기 어렵다고 저자가 말합니다. 합성 데이터, 증강 데이터를 생각해보면 가능할 것 같지 않나요?

합성 데이터는, 데이터 '양'을 늘리는 것에는 도움이 되지만, 처음부터 데이터를 만들기 위해 정의하는 것에는 한계가 있다고 합니다. 그렇기에, 기존에 마련된 공개 데이터셋을 기반으로, 저작권 문제를 해결한 데이터를 활용하는 과정에서는, 사람이 개입할 수밖에 없습니다.

특히, 지금 시대는 거짓 데이터도 넘쳐나는 시대이고, 이러한 정보가 학습되면 결국 GIGO(Garbage In, Garbage Out), 환각으로 가득한 가짜 정보만 생성될 뿐입니다. 신뢰성 또한 떨어지겠죠.

그런 지점에서 데이터셋을 큐레이션하는 직군이 더욱 돋보이는 시대가 될 것이라 생각합니다. 특히, 빅데이터 시대는 과거 통계에서 사용했던 모집단에서 샘플링 방법이 사라지고, 전수조사 형태로 활용한다는 의견이 지배적이었는데,

저작권 문제, 거짓 정보 데이터, 유해 데이터 등으로 인해 오히려 큐레이션 과정을 통한 "샘플링" 과정이 필요해진다는 점을 주목하였습니다. 데이터셋 큐레이션을 위해서는, 기준이 명확히 필요할 것이고, 그 과정에서 고려할 사항을 생각해보며 진로를 고민하게 되었습니다.

사용자 피드백

피드백이 늘 중요하다고 생각해왔고, AI도 그렇다고 생각했습니다. 본 도서가 제시한 피드백 종류가 좀 흥미로운 것은, 무심코 사용한 프롬프트가 일종의 피드백이 된다는 점이었습니다.

"내 말은 이렇게 하면 좋겠는데, 이게 진짜 원하는 거야." 이런 느낌의 프롬프팅 과정 조차 하나의 피드백이 된다는 것이고, 응답을 중간에 멈추거나 새로운 채팅으로 넘어가서 동일한 질문을 하는 경우도 "조기 종료"라는 이름으로 피드백이 될 수 있다는 것입니다.

예시로, 다음처럼 침대에 누워 쉬는 사람을 그려달라고 요청했습니다. 답변을 해주지 않아서 이 채팅창에서 대화를 종료했습니다.

이미지 없이 답변해서 조기 종료

다른 이미지 생성을 한 기록(컨텍스트)가 있는 채팅에서 실행하여 결과를 얻어냈습니다.

위 과정은 생각해보면 참 당연한 대화인데, 이를 하나의 사용자 피드백이자, "독점적으로 수집한 사용자 데이터"로 본다는 점이 새로웠습니다. 이러한 데이터를 수집하고 있다면, 이것을 바탕으로 AI 답변을 개선할 방향을 찾을 수 있겠다고 보았습니다.

피드백을 공개/비공개로 나누어 다룬 점도 생각해볼 여지가 많았습니다. 가령, 비공개 피드백을 적용하면, '좋아요'라는 피드백 수를 노출하지 않았을 때, 더 솔직한 답변이 나올 수 있으니, 더 많은 '좋아요'를 받았다는 사례도 있지만, 모르는 사람이 볼 때는, 어느 게시글이 좋아요가 많은 것인지 모르니 아예 접근하지 못할 수 있습니다.

관련해서 퇴화 피드백 루프는 좀 양극화 현상처럼 느꼈습니다. 부자는 더욱 부자가 되고, 가난한 사람은 가난해지는 느낌으로 받아들였습니다. 좋아요가 많고 인기 있는 영상은, 계속해서 더 많이 노출되고 인기를 얻습니다. "노출"이 많이 될 수 있는 구조인 것이죠. 반면 신규 영상이 새롭게 노출이 많이 될 확률은 더 낮아집니다. 과거에도 "노출 편향, 필터 버블" 과제라고 불러왔고, 도메인은 다르지만, 클라우드에서 말하는 콜드 스타트 문제와 비슷해보였습니다.

그리고 2021년 경 유튜브에서, '싫어요'라는 피드백이 비공개된 사례가 떠올랐습니다.

https://blog.youtube/intl/ko-kr/inside-youtube/2021_11_update-to-youtube/

유튜브 ‘싫어요’ 기능 관련 업데이트

blog.youtube

이 실험에서 싫어요 버튼은 그대로 표시되지만, 싫어요 수는 표시되지 않았습니다. 따라서 동영상의 싫어요 수를 늘리기 위해 싫어요 버튼을 표적으로 삼는 경향이 줄었습니다. 즉, 실험 데이터로 부터 싫어요 공격 행위가 줄었다는 점을 확인할 수 있었습니다. 또한 소규모 및 신규 크리에이터로부터 자신이 부당하게 이러한 행위의 표적이 되었다는 신고가 접수되었는데, 실험 결과 소규모 채널에서 이러한 공격이 발생하는 비율이 더 높다는 사실을 확인했습니다.

소규모 채널에서 많은 싫테(싫어요 테러)를 당하는 경우가 많았다고 하죠. 싫어요 수가 많은 영상이 되어버린 소규모 채널을 사람들이 많이 안보게 되면, 결국 앞서 말씀드린 것처럼 채널 규모에 따른 양극화가 심해질 수도 있는 노릇입니다.

이런 저런 생각을 가득한 서평이 되었는데, 요약하면 데이터셋 큐레이션과 사용자 피드백에 대한 내용이 주로 기억에 남았습니다. 앞에 AI 엔지니어링 내용은 용어를 이해하는 과정이 필요해서 반복해서 보면 좋겠고, 그 외에는 제가 떠오른 생각 위주로 정리해봤습니다.

다른 분들도 이 책을 보고 다양한 의견을 나누어봤으면 합니다.

[Do it LLM] 딥시크 기반 RAG 제작 연습

graph-dev — Tue, 21 Oct 2025 20:53:58 +0900

ollama에서 딥시크를 사용하여 챗봇을 만들어보겠습니다.

Ollama 다운

https://ollama.com

Ollama

Get up and running with large language models.

ollama.com

오라마를 내려받습니다.

ollama 모델 다운로드

langchain-ollama 다운로드

문제는 아직 에러가 많아서 제대로 실행이 안되네요. 버전 관리가 중요하다고 생각이 들었다.

최신 버전이라 실행이 안되는 걸수도 있으니,

약간의 트러블슈팅 후 다시 올려보겠습니다.

[OSSCA] PyTorch Korean Localization 2-3주차 후기

graph-dev — Thu, 16 Oct 2025 18:04:23 +0900

로고

간만에 오픈소스 컨트리뷰션 아카데미 리뷰를 남기겠습니다.

2주차 - 추석 연휴 : 오탈자 PR + 용어집 추가

2주차는 추석 연휴라서 모든 일정을 텍스트로 진행했습니다. 파이토치 튜토리얼 한글화 프로젝트의 2주차는 용어집에 추가할 단어를 선정하고 기존 번역된 문서에서 오탈자를 찾아서 이슈와 PR을 올리는 것이었습니다.

멘토님의 이야기

2주차에서 각 조별 이슈사항을 종합해보았습니다.

일단 조원분들께서 오탈자 수정 및 용어 추가를 잘 해주셨습니다. 하면서 이슈 사항은 크게 없었고, 하나 궁금한 점은 용어 추가를 하는 과정이 뭔가 모호하게 느껴져서 용어 추가하는 과정에 대한 큰 그림을 알고 싶습니다.

저와 **님만 용어 추가 및 번역 개선 과제를 수행했고, 서로 번역 개선 PR 리뷰 진행했습니다. 아래는 질문 사항입니다.
1. 꽤 많은 문서들이 영어 튜토리얼에는 있고, 한국어 튜토리얼에는 없는 이유가 궁금합니다. 특정 시기마다 영어 튜토리얼에서 일부 문서만 한국어 튜토리얼로 추가하는 건가요? 만약 그렇다면 이건 누가 하는건가요?
2. merge하려면 write access를 가진 리뷰어가 리뷰해야 한다고 하는데, 어떤 분들이 write access를 가지고 계신 것인지 궁금합니다.

크게 이슈 사항은 없었지만, 브랜치 병합 시 일부 수정이 함께 반영되는 문제가 발생하여 이를 분리하고 다시 정리했습니다. 추가로 용어 가이드에 새로운 항목을 제안할 때 어떤 기준으로 승인 여부가 결정되는지 궁금합니다.

이런 이슈사항이 재밌습니다. 어떻게 진행하고 있고, 주로 PR을 진행하고 merge될 때 과정에 대한 궁금한 점이 가득했습니다. 멘토님의 답변을 보면, 상세히 공유해주셨습니다.

정리하면, 한글/영어 튜토리얼 번역을 수행할 때 용어를 추가하는 것은 독자의 혼란을 방지하고, 일관된 문서화를 진행하기 위함입니다. 또한, 각 튜토리얼은 write access 가진 소수의 인원이 승인해야 merge가 가능하다고 합니다.

3주차 과제 - 문서 1건 통번역

3주차 과제는 1개의 문서를 온전하게 통으로 번역하는 것이었습니다. 물론, 양이 많기 때문에, 무려 2주간 진행하는 과제였습니다. 그래서 아직 진행중입니다.

다들 용어집 업데이트하면서 기존 용어에 익숙해 지셨을 거라고 믿습니다. 이제는 해당 용어들을 잘 반영해서 한국인 사용자들에게 쉬운 국문 튜토리얼을 선물할 시간입니다. 이번주, 그리고 다음주까지의 과제는 아직 번역되지 않은 튜토리얼 문서 1건을 통번역하는 것입니다. 늘 그랬듯이, 번역하고 싶은 문서를 골라 이슈를 만들어주세요! PR을 만들었다면 조별 채팅방에 공유해서 조원들에게 리뷰를 요청해 주시면 됩니다. 번역 진행하시기 전에는 이슈 목록을 확인해서 이미 누군가 진행하고 있는 문서가 아닌지, 확인 한 번 꼭 해주세요.

3주차 리뷰 - 용어집 추가 투표

3주차 미팅에 앞서 2주차에서 만든 용어에 대한 찬반 투표를 진행했습니다. 용어집 추가 PR을 바탕으로, 번역한 단어를 실제로 추가할 지 여부를 판단하는 중요한 과정입니다.

이 용어는 멘티가 찬성(Good) 이모지가 최소 7개 이상인 것을 위주로 선정할 예정입니다. 선정이 되면, 용어집 문서에 추가되고, 오픈소스 컨트리뷰터가 되는 것입니다!

대부분 찬성만 누르고, 반대는 누르지 않는 경향이 있어서, 저는 과감하게 반대 이모지를 선택했습니다. 무응답보다는 의견을 내는 것이 좋다고 생각합니다.

이렇게 해서 confusion matrix, recipe, attribution, regularization 총 4가지 용어가 선정이 되었습니다. 선정되신 분들, 모두 축하드려요!

저도 용기내어 올렸으나,

아쉽게도 미선정입니다. (내가 생각해도 이상하다 싶긴 했네요.)

3주차 미팅 - 이슈 사항

이번 주차부터는 제가 조장이 되었습니다. 이슈를 정리해보았습니다.

저, **님, **님이 번역 이슈를 올려주셨습니다. 각자 TP_**.rst, knowledge_distillation_**.py, custom_function_double_**.rst를 번역하기로 하였습니다.

오탈자 찾는게 어렵다는 의견도 있었습니다. 추석 연휴로 인해 통번역 진행이 조금 딜레이 되었습니다. 다음주 내로 파이토치 튜토리얼 독자분을 생각하며 열심히 마무리하겠습니다.

지난주 오탈자 PR을 감사하게도 다른 조에서 한분, 우제님, 건수님이 리뷰를 남겨주셨습니다. 덕분에 소스코드를 수정하고 반영하여 더 자연스러운 번역이 될 수 있었습니다.
* 오픈소스는 집단지성이 중요하다는 사실을 다시 한번 깨닫습니다.

궁금했던 점은 다음과 같습니다.
5-1. 이 레포지토리는 PR에서 Read-only permission의 승인은 어떤 의미가 있는지 궁금합니다.
5-2. 통번역 중에 용어집에 없는 단어는, 추가 이슈가 Approved 되기 전까지는 일반적으로 어떻게 표기하는지 궁금합니다.

이렇게 뒷북처럼 오픈소스는 집단 지성이 중요하다는 이야기를 강조해주었습니다. 처음부터 들었지만, 실제로 경험한 적은 거의 없었거든요.

예시로 하나 PR 올린 내용을 공유합니다.

1. Pull Request를 올립니다.

'실헌군의에서 빈도가..'로 표기된 부분을 '실험군에서'로 수정했습니다.

수정한 내역

2. PR 리뷰를 요청합니다. 어떻게든 받아내겠다는 일념으로 해야합니다.

여기서 제가 잘 수정한 줄 알았는데, 리뷰를 받고서야 어색한 점을 찾았습니다. '실험군의 트레이스에서'로 표기해야 위의 문장과 자연스럽게 이어진다는 것을 확인했습니다.

최종적으로 아래와 같이 수정했습니다.

최종 수정

자연스러운 번역이었고, 리뷰의 힘을 다시 한번 느낄 수 있었습니다.

그 결과는?

"머지(merge)"가 완료되었습니다. 음하하!

이렇게 오탈자 PR이 완료되고, 파이토치 튜토리얼 한국어 문서에 기여해보는 경험을 했습니다.

다음 과제인 통번역은 19일까지네요, 달려보겠습니다.

통번역 문서에 대한 이슈 및 PR 작성해 주시고, 번역은 19일 일요일까지 마쳐주시면 됩니다. 번역 마치신 후에는 올리면 끝이 아니라, 피드백 주고 받는 과정을 거쳐야 합니다~~! 마치신 문서에 대해서는 조에 공유하여 review 받아주시고, 문서 개선해 주세요!

[Do it LLM] 챌린지 2주차 - 스트림 출력

graph-dev — Sat, 4 Oct 2025 19:19:08 +0900

GPT API로 스트림 방식으로 출력하기 위해, stream 파라미터를 사용합니다.

stream=False : 결과를 한 번에 반환

stream=True : yield로 반환합니다. 중간마다 값을 반환합니다.

def get_ai_response(messages, tools=None, stream=True):
    response = client.chat.completions.create(
        model="gpt-4o",  # 응답 생성에 사용할 모델을 지정합니다.
        stream=stream, # (1) 스트리밍 출력을 위해 설정
        messages=messages,  # 대화 기록을 입력으로 전달합니다.
        tools=tools,  # 사용 가능한 도구 목록을 전달합니다.
    )

    if stream: 
        for chunk in response:
            yield chunk  # 생성된 응답의 내용을 yield로 순차적으로 반환합니다.
    else:
        return response  # 생성된 응답의 내용을 반환합니다.

stock_info.py 파일을 실행하겠습니다.

ai_response 함수로 한번에 답변하지 않고, 응답을 쪼개어 답변하게 되므로, for 문을 사용하게 됩니다.

    with st.chat_message("assistant").empty(): # 스트림릿 챗 메시지 초기화
        for chunk in ai_response:
            content_chunk = chunk.choices[0].delta.content # 청크 속 content 추출
            if content_chunk: # 만약 content_chunk가 있다면, 
                print(content_chunk, end="")	 # 터미널에 줄바꿈 없이 이어서 출력
                content += content_chunk # content에 덧붙이기
                st.markdown(content) # 스트림릿 챗 메시지에 마크다운으로 출력
            
            # print(chunk) # 임시로 청크 출력
            if chunk.choices[0].delta.tool_calls:	# tool_calls가 있는 경우
                tool_calls_chunk += chunk.choices[0].delta.tool_calls # tool_calls_chunk에 추가

    tool_obj = tool_list_to_tool_obj(tool_calls_chunk)
    tool_calls = tool_obj["tool_calls"]

이 코드를 실행하면 타이핑하듯이 출력됩니다. 물론 위에서 stream 파라미터가 True인 경우에 한합니다.

이제, 스트림 방식에서 Function Calling을 사용합니다. 이 결과도 조각 단위로 반환됩니다.

"불러도 대답없는 챗봇 고치기"

빈칸만 존재하네요

이제 함수를 좀 더 수정합니다. 메시지 안에 함수 정보를 넣어주고, 답변하게 합니다. 여기서 핵심은, tool_calls 안에 들어간 function 내용을 담아서 출력하는 것입니다.

    with st.chat_message("assistant").empty(): # 스트림릿 챗 메시지 초기화
        for chunk in ai_response:
            content_chunk = chunk.choices[0].delta.content # 청크 속 content 추출
            if content_chunk: # 만약 content_chunk가 있다면, 
                print(content_chunk, end="")	 # 터미널에 줄바꿈 없이 이어서 출력
                content += content_chunk # content에 덧붙이기
                st.markdown(content) # 스트림릿 챗 메시지에 마크다운으로 출력
            
            # print(chunk) # 임시로 청크 출력
            if chunk.choices[0].delta.tool_calls:	# tool_calls가 있는 경우
                tool_calls_chunk += chunk.choices[0].delta.tool_calls # tool_calls_chunk에 추가

    tool_obj = tool_list_to_tool_obj(tool_calls_chunk)
    tool_calls = tool_obj["tool_calls"]   

    if len(tool_calls) > 0: # 만약 tool_calls가 존재하면, st.write로 tool_call 내용 출력
        print(tool_calls)
        # tool_calls에서 function 정보만 모아서 출력
        tool_call_msg = [tool_call["function"] for tool_call in tool_calls]
        st.write(tool_call_msg) 

    print('\n===========')
    print(content)

이렇게 출력하면 아래와 같은데,

[{'id': '**', 'function': {'arguments': '{"ticker": "TSLA", "period": "1d"}', 'name': 'get_yf_stock_history'}, 'type': 'function'}, {'id': 'call_0My0oR1YFDqASvDfhwREoAE9', 'function': {'arguments': '{"timezone": "America/Los_Angeles"}', 'name': 'get_current_time'}, 'type': 'function'}]

===========

[{'id': 'call_bZc69QZwdTk33jB4CIs8Zeh8', 'function': {'arguments': '{"ticker": "TSLA", "period": "1d"}', 'name': 'get_yf_stock_history'}, 'type': 'function'}, {'id': '**', 'function': {'arguments': '{"timezone": "America/Los_Angeles"}', 'name': 'get_current_time'}, 'type': 'function'}]

여기서 function으로 된 키 값을 추출하면 다음과 같다.

'function': {'arguments': '{"ticker": "TSLA", "period": "1d"}',
'name': 'get_yf_stock_history'}

...

'function': {'arguments': '{"timezone": "America/Los_Angeles"}',
'name': 'get_current_time'}

자 tabulate 모듈을 설치합니다.

이제 tabulate 설치가 완료되었고, 다시 실행합니다.

아래와 같이, 펑션 콜링을 수행할 때, 함수가 잘 나오고 그 뒤에 답변이 나타나는 것을 알 수 있습니다. 어느 함수를 사용했는지 이 빈 칸에 넣게 됩니다.

결과

이렇게 잘 함수가 출력되고, 그 펑션 콜링을 바탕으로 아래 답변이 나타나는 것을 알 수 있습니다.

[클로드 코드] 챌린지 2주차 - 프롬프트 작성

graph-dev — Wed, 1 Oct 2025 14:15:55 +0900

클코

프롬프트

CLAUDE.md로 설정을 마치고, 요청을 잘하기 위해 프롬프트를 "잘" 만들어야 합니다.

이제 효과적인 프롬프트 작성법, 컨텍스트 최적화로, 클로드 협업 효율성을 높이겠습니다.

1. 프롬프트 엔지니어링 기초

프롬프트 1 : 단순히 "무엇을 해줘" → 0점입니다. 중요 맥락이 빠지면서 결과가 부정확할 수 있네요.

가령, 회원가입 기능 구현해줘는 어떨까요?

어떤 기술 스택을 사용할지
어떤 필드가 필요한지
어떤 검증 규칙이 필요한지
프론트엔드만? 백엔드도?
데이터베이스 연동은?

전부 누락되겠습니다. 이것을 보완해보면 다음과 같습니다.

React와 Node.js/Express를 사용해서 회원가입 기능을 구현해줘.
- 필드: 이메일, 비밀번호, 비밀번호 확인, 이름
- 이메일 형식 검증과 비밀번호 강도 체크 포함
- 프론트엔드 컴포넌트와 백엔드 API 엔드포인트 모두 필요

한번 더 구체화해서 프롬프트를 만들어 보겠습니다.

회원가입 시스템을 만들고 싶어. 다음 사양으로 구현해줘:

기술 스택:
- 프론트엔드: React with TypeScript
- 백엔드: Node.js + Express
- 데이터베이스: PostgreSQL

필수 기능:
1. 회원가입 폼 (이메일, 비밀번호, 이름, 전화번호)
2. 유효성 검증:
- 이메일 중복 확인
- 비밀번호: 최소 8자, 대소문자+숫자+특수문자 포함
- 전화번호 형식 검증
3. 비밀번호 해싱 (bcrypt 사용)
4. 가입 성공 시 JWT 토큰 발급
5. 에러 처리 및 사용자 피드백

추가 요청:
- 폼 제출 중 로딩 상태 표시
- 깔끔한 UI (Tailwind CSS 사용)
- API 응답 형식은 JSON

이렇게 배경지식, 출력 형식, 제약 조건을 언급하는 것이 좋습니다.

프롬프트 구성요소

1. 컨텍스트(Context) : 배경 정보로 프로젝트 환경, 기술 스택, 목표와 제약 조건 등이 해당합니다.

2. 구체적인 요구사항 : 맥락으로 부족하고, 기능과 기술 조건을 구체적으로 기술합니다.

3. 예상 결과물 : 반복 요청을 줄일 수 있습니다. 바로 활용 가능하도록 결과물을 만듭니다.

컨텍스트 최적화 전략

1. 작업 범위 명확히 제한하기

이거 보다는, 특정 디렉터리만으로 제한하여 명령합니다.

claude --add-dir 디렉터리 "해당 디렉터리 코드에서 버그를 찾아주세요"

2. 단계적 접근법(Narrow Down)

한번에 해결하지 말고, 큰 그림, 의심하는 영역, 원인 순으로 좁혀나가세요.

2-1. "전체 구조를 분석해서 문제가 있을 만한 영역을 찾아주세요"

2-2. "특정 디렉터리 API" "API 호출할 때, 성능 이슈를 찾아주세요"

2-3. "@디렉터리/특정 파일 이 파일의 메모리 누수 원인을 찾아주세요"

토큰 관리와 세션 최적화

1. 토큰 효율성 고려하기

요금제별 모델 정책을 이해하고 사용합니다. Opus, 비싸고 강력한 것은 숨겨둔 한 수로 사용합니다.

특히, 입력도 토큰 소진이 되겠죠. 괜히 길게 프롬프트 쓰지 말라는 뜻이에요. 두괄식으로 깔끔하게 갑시다.

2. 모델 쿼터 관리하기

비싼 Opus 다 쓰면, Sonnet을 쓰는 것처럼, 주어진 쿼터를 고려해서 작업하는게 좋습니다.

3. 세션 관리 명령어

대화가 길면 컨텍스트가 커지므로, /compact, /clear, /status를 조합하여 사용합니다.

/compact 는 응답이 느리면 쓰고, /clear는 다른 주제일 때 쓰고, /status는 모니터링 용도입니다.

4. Auto-Compact 모니터링

토큰 임계치 관리의 핵심 방법으로, 자동 압축을 합니다. 압축률을 관리해서 임계치에 도달했는지 볼 수도 있습니다. 이 자동 압축 수치는 성능 지표, 정보 손실 경고, 작업 효율성 측면에서 이를 고려해야 합니다.

최적의 전략은, 50% 이상 압축률은 /clear로 새롭게 하고, 완전 낮으면 /compact로 컨텍스트를 간소화합니다. 적절한 압축률이면 /status를 보면서 넘어가는거죠.

5. 권한 모드 --permission-mode

이 명령어는 여러 가지가 속합니다. permission mode, acceptEdits, plan, bypassPermission

반복 작업을 빠르게 자동화(acceptEdits, bypass 등)하거나 단계적 실행(plan)에 유용한데, 신뢰성 및 안전성을 고려해서 사용해야 합니다.

6. 언어 선택도 전략적으로 합니다. 한글은 토큰을 많이 쓰고, 영어는 기술 정확성과 효율성이 높습니다.

그러면 한글은 안 쓰는게 좋을까요? 그렇지 않습니다.

한글은, 한국인이라면 자연스럽게 의도를 전달하고, 복잡한 비즈니스 로직도 쉽게 설명할 수 있습니다.

영어는 기술 정확성과 우수한 토큰 사용량, 간결한 표현에서 좋습니다. 요금제가 낮은 클로드를 사용하시면, 영어를 권장합니다.

특수 문자 숏컷: 프롬프트 효율화

1. @ - 파일 참조 : 파일 내용 직접 가져와서 프롬프트에 넣어 명령할 수 있습니다.

2. ! 시스템 명령어 실행 : 사용자 터미널에서 직접 실행

여러 줄 입력

\ 엔터키가 일반적이고,

일부 맥 터미널은 옵션 + 엔터,

itemr2, vscode 터미널 /terminal-setup 설정으로 쉬프트 + 엔터로 여러 줄 입력을 할 수 있습니다.

더 길어진다면, 별도 파일로 프롬프트 작성하고 @파일 숏컷을 사용합시다.

그 외에도, 작업 디렉터리별로 명령어 히스토리를 사용합니다. 방향키 위/아래를 사용합니다.

계층적 질문 전략

큰 그림 파악 > 세부 기능 구현 > 세부 튜닝

복잡한 task는 이렇게 좁혀가며 활용하는 것이 좋습니다.

실전 프롬프트 템플릿

교재에는 전용 템플릿이 있어, 상황별로 적절히 수정할 수 있도록 제공하고 있습니다.

실습: 프로젝트 기획

1. 프로젝트 기획서 작성

프로젝트로 개발할 웹 애플리케이션을 기획해줘.

조건:
- 주제: 지방소멸위험 알리미 서비스
- 기간: 3개월 (2025.03 - 2025.05)
- 팀: 2명 (풀스택 개발자 1명, 디자이너 1명)
- 예산: 1000만원 이내

고려사항:
- 실용성과 편의성
- 유지보수 및 확장 가능성

결과물:
- 프로젝트 개요
- 주요 기능 3개
- 기술 스택 추천
- 주차별 개발 일정
- 예산 분배 방안

2. 기술 스택 선정

앞에서 기획한 프로젝트에 적합한 기술 스택을 추천해줘.

고려사항:
개발 속도 (빠른 프로토타이핑)
클라이언트 요구사항
개발 생산성
배포 및 유지보수
비용 효율성

비교 기준:
프론트엔드: React vs Vue vs Angular
백엔드: Node.js vs Python vs Java
데이터베이스: PostgreSQL vs MongoDB vs Firebase
배포: AWS vs Netlify vs Vercel
상태관리: Redux vs Zustand vs Context API

결과물:
추천 기술 스택 (이유 포함)
단계별 가이드
대안 기술 스택
마이그레이션 기획

기술 스택

3. 개발 환경 세팅

선정한 기술 스택으로 개발 환경을 세팅해주세요.

요구사항:
팀 협업 환경 (Git, EsLint, Prettier)
개발 효율성 (Hot reload, 디버깅)
코드 품질 (TypeScript, 테스트)
CI/CD 파이프라인 기초

단계별 가이드:
프로젝트 초기화 패키지 설치 및 설정 디렉터리 구조 생성 기본 컴포넌트 생성 Git 설정 배포 준비

결과물:
완전한 세팅 명령어
설정 파일
팀 공유용 README
트러블슈팅 가이드

결과 확인

각 단계별로 환경을 세팅하고, 정리하면 아래와 같습니다.

고급 프롬프트 기법

1. 롤플레잉 기법

- 이전에 페르소나를 부여해서 작업하는 방식과 동일합니다.

- 전문가 역할을 넣어 답변의 깊이를 높이네요.

2. 단계별 사고 유도

- 이전에 CoT라고 하는, 복잡한 과제를 단계별로 작은 단위 분해해서 체계적으로 접근하게 만드는 방법입니다.

- Chain of Thought

문제 해결 팁

실수 1: 너무 모호한 요청

ex) 웹 사이트 예쁘게 만들어 줘 > 어떤 페이지를 개선해주고, 개선할 기능 요구사항을 명확히 합니다.

실수 2: 컨텍스트 정보 부족

ex) 버그 고쳐줘 > 이거보다는 해당 버그 메시지를 가져오는 게 좋습니다.

[클로드코드] 챌린지 기록 2주차 1일 - CLAUDE.md

graph-dev — Mon, 29 Sep 2025 22:08:48 +0900

클로드 md(마크다운) 파일을 통해 클로드 코드를 설정합니다. 교재에서는 개발자처럼 일할 수 있도록 정보 제공 지침서라고 표현합니다.

클로드 코드 핵심이 되는 이 마크다운 파일, /init 명령어를 활용해서 설정합니다.

CLAUDE.md

자동으로 프로젝트 맥락을 포함하고, 코딩 스타일과 규칙을 저장하고, 세션이 끝나도 메모리가 유지되고, 계층적인 구조로 여러 파일을 조합해서 설정할 수 있는 장점이 있습니다.

/init 명령어

이 명령어로, 현재 디렉터리를 분석하고, 프로젝트에 맞는 CLAUDE.md 파일을 생성합니다. 온보딩 가이드를 만들어주네요.

실제 프로젝트로 실습해봅니다. 교재에서 진행한 것처럼 '간단한' 리액트 프로젝트를 만들었습니다.

새로운 경로 생성

npx create-react-app my-react-app 명령어로 리액트 프로젝트를 생성합니다.

npx create-react-app my-react-app

생성하고, cd my-react-app 으로 프로젝트 경로로 들어갑니다. 단, 실행하지 않고, 여기서 claude를 불러옵니다.

CLAUDE.md 파일을 만들거냐고 묻는데, yes로 눌러서 진행합니다. 아래와 같이 작성이 됩니다.

이제 같은 방법으로, Express.js 환경을 만들어줍니다. 이게 백엔드 역할을 한다고 합니다.

express.js 초기화

이제, 클로드 코드에서 /init 명령을 바로 실행합니다.

claude /init

작성된 CLAUDE.md 파일은 다음과 같습니다.

알아서 잘 만드는 클로드

리액트와 Express 모두 /init으로 각 맥락에 맞는 가이드 문서를 제공해줍니다. 알아서, 잘, 딱, 깔끔하고 센스있네요?

CLAUDE.md 커스텀

내 의도를 잘 반영하려면, 수동으로 고치거나 클로드 코드에게 고쳐달라고 프롬프트에 넣어 요청합니다.

원하는 경로로 들어가서, claude를 실행하고, "이 프로젝트에 적합한 CLAUDE.md 파일 만들어줘"로 실행하면 됩니다.

그 후에도 마음에 들지 않는다면, 그 부분을 위주로 고치면 되겠죠?

CLAUDE.md 파일을 팀과 개인 구분하여 사용하기

메모리 스코프라는 개념을 활용합니다. 정리하면, 개인용 맥락은 User Scope, 팀 전체 공용은 Project Scope에서 가져오는 것이 좋습니다.

프롬프트 작성 원칙은 간결하고, 선언적 형태로, 토큰을 아끼고, 실시간 업데이트로 주기적인 개선을 진행합니다. 5가지 필수 포함할 요소가 있습니다.

1. 기술 스택

2. 프로젝트 구조

3. 핵심 명령어

4. 코딩 스타일

5. 저장소 규칙

CLAUDE.md 응용 고급 팁

계층적으로 사용하세요. 영역별로 디렉터리를 나누고, 전체적으로 CLAUDE.md 파일을 두고, 각 서브 디렉터리(프론트엔드, 백엔드, 문서 등)마다 하나씩 CLAUDE.md 파일을 생성하여 관리하는 것이 좋습니다.

동적 CLAUDE.me 관리해주세요. 한 번 작성하고 끝내지 말고, 진행률에 따라 지속적으로 업데이트해야합니다. 각 단계별 현재 상태와 우선순위를 반영해주면 더 활용하기 좋겠습니다.

마지막으로, 팀 단위 프로젝트에서 협업을 위해 사용하세요. CLAUDE.md에 코드 리뷰 규칙, 팀 역할 등을 명확히 해주면, 신규 직원이 오더라도 신속한 온보딩과 기존 팀원도 참고하기 좋은 훌륭한 인수인계 자료가 됩니다!!

CLAUDE.md 활용 전략

프로젝트별로 맞춤 설정을 합니다. 프로젝트가 기업과 계약하는 경우 상황과 일정을 조정하고, 개인 학습은 도전적인 시도와 품질 향상이 메인이 되어 작성해주면 됩니다. 팀 단위에서는 역할, 코드 리뷰 규칙, 협업 기준을 모두 담아둡니다. 신규 직원 온보딩 등에 좋고, 프로젝트 전체 품질, 일관성을 유지합니다. 또한, 토큰 효율성을 높이려면, 핵심 정보만 정리해서 클로드에게 물어보세요. 답변도 짧게 나와서 토큰을 아낄 수 있습니다.

<비효율적 토큰 사용>

이 프로젝트는 Python을 기반으로 데이터 분석을 하고, Streamlit으로 시각화를 합니다.

<효율적 토큰 사용>

# Tech Stack

- Python 3.12 + Streamlit

자동 업데이트 워크플로

지속적으로 프로젝트가 진행되면, 이러한 상황을 클로드에게 알려줘서 반영시켜야합니다. 기술 스택이 바뀌거나 새 팀원이 오면 넣어줄 문서를 CLAUDE.md에 추가하는 형식으로 진행하였네요.

그 외 문제 해결과 팁을 살펴봅니다.

팀원마다 다른 설정 사용?
- 개인별 설정 파일을 .gitignore에 두고 CLAUDE.md가 이를 참고하게끔 구성합니다.
- 아까 보셨던 개인별 User Scope의 .md 파일(~/.claude/CLAUDE.md)을 활용하면, 개인과 팀(프로젝트 경로)이 섞이지 않습니다. 경로가 완전히 달라지니까요.

이렇게 CLAUDE.md 파일을 만들어보고, 각 프로젝트별로 생성하고 업데이트해보았습니다. 나아가 팀과 개인을 나누어 볼 수 있도록 여러 계층으로 이 md 파일을 만들어두는 것도 좋은 방법이라 생각합니다.