지정해주신 소스 문서(raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md)의 분석을 바탕으로, 요구사항 및 frontmatter 스키마를 완벽히 준수한 ‘구조적 코드 린팅’ 한국어 위키 노트를 작성하여 프로젝트 경로 내 /Users/railscraft/.gemini/antigravity-cli/scratch/llm-wiki/wiki/구조적 코드 린팅.md 파일로 생성을 완료하였습니다.
작성된 위키 노트 내용
---
type: workflow
status: draft
core: false
tags:
- llm
- agent
- code-quality
- guardrails
aliases:
- Structural Code Linting
- AST 기반 린팅
sources:
- 'raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md'
created: 2026-08-27
updated: 2026-08-27
---
# 구조적 코드 린팅
## 한 줄 정의
구조적 코드 린팅(Structural Code Linting)은 코드의 단순 표면 포맷(띄어쓰기, 변수명 정렬 등)을 점검하는 것에 그치지 않고, 추상 구문 트리(AST) 수준에서 소스 코드의 문법 구조와 논리적 뼈대를 분석하여 AI 에이전트나 개발자가 주입할 수 있는 구조적 결함 및 안티 패턴을 정밀 검증하고 차단하는 품질 및 보안 가드레일 기술이다.
## 핵심 요지
- **논리적 위상 스캔**: 단순 문자열 매칭이나 표면적 포맷팅 검사(예: 공백, 변수명 린팅)와 달리, 구문 분석기가 생성한 [[추상 구문 트리]](AST) 구조에 기반하여 소스 코드의 데이터 흐름과 위상학적 구조를 분석한다.
- **AI 에이전트 기형 코드 예방**: LLM 에이전트가 짠 코드는 포맷팅이나 타입 정의가 깔끔하더라도 논리 설계상 치명적인 오작동(예: 파이썬의 변경 가능한 디폴트 매개변수 `def process(items=[]):`, 비어있는 예외 처리 `except: pass`)을 포함할 수 있으며, 구조적 린팅은 이를 자동 탐지해 차단한다.
- **AST 기반 패턴 매칭 도구 활용**: AST-grep과 같은 정적 분석 도구를 사용하여 문제 구조를 포착하는 탐지 규칙을 작성하고, 배포 파이프라인이나 [[커밋 전 게이트]](Pre-Commit Gates)에 연동하여 자율적 품질 검증 파이프라인을 구축한다.
## 상세
[[AI 에이전트]]가 작성한 코드에서 발생하는 버그 중 상당수는 겉보기에 포맷팅이 우수하고 타입 체커나 일반 린터를 문제없이 통과하지만, 실행 시점에 끔찍한 사이드 이펙트를 유발하는 구조적 결함을 포함하곤 한다. 이는 LLM이 웹상의 방대한 학습 데이터 중 안티 패턴이나 허술한 예외 처리 구문을 필터링 없이 학습하여 그대로 재현하기 때문이다 (`raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md`).
전통적인 린터가 띄어쓰기, 네이밍 스타일 등 외형을 가볍게 점검한다면, **구조적 코드 린팅**은 소스 코드를 단순 텍스트로 취급하지 않고 언어 구문 분석기가 변환한 추상 구문 트리(AST, Abstract Syntax Tree)를 바탕으로 데이터의 안전성과 문법 구성을 정밀 계측한다 (`raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md`).
구조적 코드 린팅은 [[가드레일 레이어]]의 주요 구성 요소로 기능한다. 개발자가 에이전트의 반복적인 구조적 결함 패턴을 매번 수동 리뷰로 수정해 주는 대신, 포착하려는 AST 트리 형태의 검증 규칙을 정립하여 [[커밋 전 게이트]](Pre-Commit Gates)나 CI/CD 파이프라인에 강제로 내장시킴으로써 위험한 패턴의 코드베이스 유입을 원천 봉쇄할 수 있다 (`raw/30 Core Agentic Engineering Concepts Every Developer Should Know.md`).
## 예시
### 파이썬 변경 가능한 디폴트 매개변수(Mutable Default Argument) 탐지 및 예외 생략 차단
AI 에이전트가 자주 생성하는 파이썬 안티 패턴 중 하나는 함수 정의 시 기본 매개변수로 가변 객체(리스트, 디셔너리 등)를 지정하는 것이다.
```python
# 안티 패턴: 함수 구동 시 생성된 메모리 리스트 객체가 향후 호출마다 공유되어 데이터가 누적 오염됨
def process(items=[]):
items.append("data")
return items
# 예외 생략 안티 패턴: 에러 발생 시 원인을 마스킹하고 무시함
try:
risk_operation()
except:
passAST-grep 도구를 활용하면 이러한 AST 위상 구조를 정확히 조준하여 정적 분석 검사 규칙(rule)을 작성할 수 있다.
# ast-grep 규칙 예시 (Python mutable default argument 탐지)
id: mutable-default-argument
language: python
rule:
pattern: def $FUNC($...ARGS, $PARAM=[], $...REST): $$$BODY
message: "변경 가능한 디폴트 매개변수(mutable default argument)가 사용되었습니다. None을 기본값으로 사용하고 함수 내부에서 초기화하십시오."
severity: error이 규칙을 배포 및 프리커밋 게이트에 등록해 두면, 에이전트가 커밋을 시도할 때 문법적으로 완벽해 보이는 이 기형 코드를 커밋 단계에서 가로막고 에러 로그를 반환하여 에이전트가 스스로 교정하도록 유도한다.
충돌
본 문서와 관련된 소스 문서 간 충돌 사항은 발견되지 않았다.