YAML 포맷과 yamllint 검사를 분리하기
Oxfmt, yamllint, YAML 스키마의 역할을 나누고 Tasks의 진단을 Problems 창에 연결합니다.
자료 확인일: 2026-09-06. 예제는 별도 format-lab 프로젝트에서 순서대로 적용합니다. 명령은 macOS·Linux·WSL의 프로젝트 루트 기준이며, 기존 설정에는 필요한 키를 병합합니다.
YAML에는 세 종류의 검사가 필요합니다
YAML이 들여쓰기까지 예쁘게 정리되어 있어도 replicas: many가 배포 가능한 설정은 아닙니다. 이 문서에서는 Oxfmt가 포맷, yamllint가 중복 키와 표기 규칙, Red Hat YAML 확장이 스키마 진단을 맡습니다. YAML 확장이 .yamllint.yaml을 실행하는 것은 아닙니다. YAML 확장의 스키마 지원
설정 파일을 준비합니다
Oxfmt·Oxlint 실습의 Oxfmt 설정을 그대로 사용합니다. Python 도구 실행에는 uv를 준비합니다. 처음 만드는 실습 폴더에서만 uv init --bare를 실행하고 이미 pyproject.toml이 있으면 생략합니다. uv add가 만든 의존성 선언과 uv.lock을 커밋합니다.
uv init --bare
uv add --dev --bounds exact yamllint
code --install-extension redhat.vscode-yaml루트 .yamllint.yaml:
extends: default
rules:
document-start: disable
line-length: disable
braces:
min-spaces-inside: 0
max-spaces-inside: 1
truthy:
allowed-values: ["true", "false"]
check-keys: false
ignore: |
node_modules/
.venv/
dist/문서 시작 ---는 선택 사항으로 두고 줄 길이는 formatter와 충돌하지 않게 끕니다. 중괄호 안 공백은 Oxfmt의 flow mapping 출력도 허용합니다. truthy.check-keys: false는 GitHub Actions의 on 같은 키를 허용하기 위한 선택이며 값의 yes는 계속 진단합니다. 프로젝트에 필요 없는 완화는 되돌려도 됩니다. yamllint 설정
.vscode/settings.json에 병합합니다. yaml.format.enable: false로 포맷 소유권을 Oxfmt에 둡니다.
{
"[yaml]": {
"editor.defaultFormatter": "oxc.oxc-vscode"
},
"yaml.format.enable": false,
"yaml.validate": true,
"yaml.schemas": {
"./config/app.schema.json": "config/app.yaml"
}
}외부 스키마 다운로드 없이 실험하도록 config/app.schema.json도 만듭니다.
{
"$schema": "https://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": ["name", "enabled", "replicas"],
"properties": {
"name": { "type": "string" },
"enabled": { "type": "boolean" },
"replicas": { "type": "integer", "minimum": 1 }
}
}실패를 보고 사람이 의미를 결정합니다
config/app.yaml의 잘못된 예:
name: api
enabled: yes
replicas: 2
replicas: 3yamllint는 중복 키와 yes 표기를 진단합니다. 포맷터에 어느 replicas를 남길지 결정하게 하지 않습니다. 먼저 사람이 중복을 없애고 boolean을 명시합니다.
name: api
enabled: true
replicas: 3아래 첫 명령은 잘못된 파일에서 실행해 실패를 관찰합니다. 수정한 뒤 나머지 명령을 실행합니다. -s는 warning도 실패로 취급하는 엄격 모드입니다. yamllint에는 여기서 사용할 자동 수정 단계가 없습니다.
uv run --locked yamllint -c .yamllint.yaml config/app.yaml
npm exec -- oxfmt config/app.yaml
uv run --locked yamllint -c .yamllint.yaml -s config/app.yaml
npm exec -- oxfmt --check config/app.yaml이번에는 replicas: many로 바꿔 봅니다. 이는 유효한 YAML이라 yamllint만으로 애플리케이션 타입을 보장하지 못합니다. 스키마가 연결된 편집기는 integer 위반을 보여야 합니다. CI에서도 같은 보장이 필요하면 별도 스키마 검증이나 실제 소비 프로그램의 검증 명령을 추가합니다.
yamllint 결과를 Problems 창에 연결합니다
.vscode/tasks.json을 만듭니다. 이 task는 저장 시 자동 실행되지 않으며 Tasks: Run Task → lint:yaml로 호출합니다.
{
"version": "2.0.0",
"tasks": [
{
"label": "lint:yaml",
"type": "process",
"command": "uv",
"args": [
"run",
"--locked",
"yamllint",
"-c",
".yamllint.yaml",
"-f",
"parsable",
"-s",
"config"
],
"options": { "cwd": "${workspaceFolder}" },
"problemMatcher": {
"owner": "yamllint",
"fileLocation": ["relative", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.+):(\\d+):(\\d+): \\[(warning|error)\\] (.+)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"message": 5
}
}
}
]
}parsable 출력의 파일·줄·열·심각도를 matcher에 연결합니다. 일부러 yes를 다시 넣고 task를 실행해 Problems 항목에서 정확한 위치로 이동하는지 확인합니다. VS Code problem matcher
암호화 YAML, Helm·Jinja 템플릿, 외부에서 고정한 manifest는 일반 YAML과 다르게 취급할 수 있습니다. 실제 대상 파일을 기준으로 Oxfmt와 yamllint 양쪽 제외 범위를 맞추고, 제외 이유와 대신 수행할 검사를 적습니다.