코딩 기초 사용법 (2026년 6월 개정판)

1. 프로젝트 시작

프로젝트를 시작할 때는 폴더를 만들고, 그 안으로 이동한 뒤 uv init으로 기본 셋업을 진행한다.

mkdir my_project
cd my_project
uv init

uv init을 실행하면 pyproject.toml, .python-version, main.py 등 기본 파일이 자동으로 생성된다. pip 대신 uv를 쓰는 이유는 속도도 빠르고, 가상환경과 패키지 관리를 한 번에 처리해줘서 편하기 때문이다.

패키지 설치도 pip install 대신 uv add를 사용한다.

# pip install requests  ← 이렇게 하지 않는다
uv add requests

2. AI Agent 사용법

터미널에서 프로젝트 경로로 이동한 뒤 AI agent를 호출한다. 나는 CLI 버전 Claude를 쓰는데 이건 취향 차이다.

cd my_project
claude  # 또는 codex

처음 시작할 때 claude init 같은 초기화 명령을 쓸 수도 있는데 굳이 안 해도 된다. 대신 CLAUDE.md 파일을 만들어서 agent에게 프로젝트 규칙을 미리 알려두는 게 핵심이다. 이렇게 해두면 매번 같은 말을 반복하지 않아도 되고, 토큰도 절약된다.

CLAUDE.md 파일은 아래 구조로 작성한다.

my_project/
├── CLAUDE.md       ← agent에게 전달할 수칙
├── pyproject.toml
├── main.py
└── src/
    ├── pipeline_a.py
    └── pipeline_b.py

CLAUDE.md 예시

아래는 실제로 사용하는 형식의 예시이다.

공통 수칙

pip 대신 uv를 통한 프로젝트 관리를 진행한다. pip install → uv add 방식으로 패키지를 관리한다.

기능을 추가할 때마다 git commit을 통해 해당 기능에 대한 설명을 남긴다.

main에 코드를 몰아넣지 않고, 용도별로 폴더와 파일을 나눠서 코드를 정리한다. 프로젝트가 복잡하다면 레이어를 나눠서 폴더별 세부 기능 코드를 정리하는 파이프라인을 만들고, 그 파이프라인들을 묶어서 호출하는 하나의 파일을 만든다. 최종적으로 보는 코드는 가독성 좋게 흐름을 파악하는 것을 목적으로 한다.

프로젝트 설명

개요 / 목적: 이 프로젝트는 [목적]을 위해 진행한다. 나는 [이것]을 주면 [이것]을 받는 프로젝트를 만들고 싶다. 현재 내가 가진 것은 [이것]이고, 자세한 내용은 추후 설명하겠다. 최종적으로 얻고 싶은 형태는 [이것]이며, 나중에는 [이런 모습]까지 확장할 생각이다.

데이터 설명 (현재 보유 데이터 스키마):

A 테이블

id : text : 고유 코드 (unique)

name : str : 사람 이름

…

추가 설명: 하나의 id에는 이름이 하나씩 매핑된다. B 테이블에는 A와 B가 1:N으로 매핑되어 [이런 케이스]가 발생한다. 이 경우 더 이상 로그가 올라오지 않기 때문에 [이렇게 됐는지 저렇게 됐는지] 확인이 불가능하다.

말투 및 응답 방식

나는 [이 정도] 수준의 지식을 가지고 있다.

코드는 전체 내용을 매번 새로 주지 말고, 수정된 필요한 부분만 발췌해서 주면 내가 직접 정리하거나 수정한다.

내가 진행하는 프로젝트 구조나 사용 도구보다 더 효과적이고 새로운 방식이 있다면 적극적으로 제안해 주길 바란다.

README는 작업할 때마다 쓰지 말고, 최종 프로젝트가 끝난 뒤 요청하면 그때 작성한다.

내가 직접 선언한 코드들에 대해서는 원본을 최대한 유지한다.

이런 식으로 CLAUDE.md를 세팅하고 프로젝트를 시작하면 토큰 절약과 함께 원하는 방향대로 진행할 수 있다.

3. VSCode 열기

터미널에서 프로젝트 경로로 이동한 뒤 아래 명령어로 VSCode를 바로 열 수 있다.

code .

명령어가 실행되지 않는다면 VSCode를 열고 Cmd+Shift+P → Shell Command: Install 'code' command in PATH를 실행하면 된다.

4. 디버그 하는 법

AI와 함께 프로젝트를 진행하더라도 디버그만큼은 직접 해야 하는 경우가 많다.

디버그의 핵심은 문제를 범위를 좁혀가며 원인을 찾는 것이다. 선풍기 비유로 설명하겠다.

어느 날부터 집에 선풍기가 돌아가지 않는다. 어떻게 해야 할까?

① 전기는 제대로 들어오는가? → 변수가 정상인지 확인

콘센트 자체가 문제인지 확인하려면 같은 구멍에 헤어드라이기를 꽂아본다. 코드로 치면, 다른 값을 넣어봐서 함수가 정상 작동하는지 확인하고, 변수의 타입이 맞는지 본다.

print(type(my_variable))   # 타입 확인
print(my_variable)          # 값 자체 확인

② 선풍기 모드를 하나씩 눌러본다 → 함수의 정상 작동 범위 확인

특정 모드에서만 안 되는 건지, 전체가 안 되는 건지 확인한다. 코드로 치면, 특정 입력값에서만 오류가 나는 건지, 아예 동작 불가인 건지 범위를 좁히는 것이다.

# 정상 케이스와 오류 케이스를 각각 직접 넣어서 비교
result_ok  = my_function("정상_값")
result_err = my_function("문제가_생기는_값")
print(result_ok, result_err)

③ 멀티탭 불량 여부 확인 → 중간 처리 과정을 생략하고 직접 연결

멀티탭(중간 처리)을 건너뛰고 벽 콘센트에 직접 연결해본다. 코드로 치면, 파이프라인을 통하지 않고 변수를 함수에 직접 넣어 확인하는 것이다.

# 파이프라인을 거친 값 대신, 직접 선언한 값을 넣어본다
a = 1
b = 2
result = my_function(a, b)
print(result)

④ 부품 불량 의심 → 외부 라이브러리 문제 여부 확인

선풍기를 해체해서 부품 하나씩 연결하며 확인한다. 코드로 치면, 외부 라이브러리를 사용하는 경우 최종 결과만 볼 게 아니라 중간 호출 단계마다 값을 찍어본다.

import requests
 
response = requests.get("https://example.com/api")
print(response.status_code)   # 라이브러리 호출 자체가 정상인지
print(response.text)           # 반환된 내용이 예상한 형태인지

디버그는 결국 가정 → 검증 → 범위 축소의 반복이다. 한 번에 여러 가지를 바꾸지 말고, 한 번에 하나씩 바꿔가며 원인을 좁혀나가는 게 핵심이다.

긍정우

Explorer

04_코딩 기초 사용법 (2026 6월 개정판)_블로그