제약-주도 개발 (Constraint-Driven Development)

제약-주도 개발 (Constraint-Driven Development)은(는) 무엇을 하나요?

개요

이 팩의 다른 스킬들은 '좋은 코드'가 무엇인지 설명합니다. code-review-and-quality는 다섯 가지 축을 제공합니다. test-driven-development는 개발 사이클을 제공합니다. security-and-hardening은 위협 목록을 제공합니다. 이 모든 것은 에이전트가 읽고 따를 수도 있고 따르지 않을 수도 있는 일반적인 설명에 불과하며, 세션이 끝나면 사라집니다.

이 스킬은 다른 것을 만듭니다: 이 프로젝트의 품질 기준을 숫자로 기록하여, 대화가 끝난 후에도 남아 있고 기계적으로 확인할 수 있는 문서를 생성합니다.

그 이유는 중요합니다. 당신이 코드를 직접 작성할 때는 코드를 읽는 것만으로도 품질을 판단할 수 있었습니다. 하지만 에이전트는 당신이 일주일 동안 읽을 수 있는 양보다 더 많은 코드를 한 오후에 작성합니다. 따라서 판단의 주체는 당신의 머리에서 루프를 도는 자동 검사로 이동합니다. 이러한 검사는 존재해야 하고, 당신이 실제로 선택한 숫자를 기준으로 해야 하며, 에이전트가 스스로 결과물을 수정할 수 있도록 작업에 충분히 가깝게 실행되어야 합니다.

명세-주도 개발(Spec-driven development)은 무엇을 만들지 정의합니다. 테스트-주도 개발(Test-driven development)은 그것이 작동한다는 것을 증명합니다. 제약-주도 개발(Constraint-driven development)은 '출시하기에 충분히 좋은' 것이 무엇인지, 누군가가 풀 리퀘스트에서 논쟁을 시작하기 전에 정의합니다.

사용 시기

이 스킬은 다음과 같은 경우에 적용하십시오:

• 프로젝트나 주요 기능을 시작하는데 품질 기준이 문서화되어 있지 않은 경우
• 사용자가 "제약 조건 설정", "품질 게이트 추가", "표준 정의", 또는 "에이전트가 쓰레기를 배포하지 못하게 해"라고 요청할 때
• 에이전트가 아무도 한 줄 한 줄 읽지 않을 정도의 코드를 생산하는 경우
• CI에 검사가 있지만 어떤 것이 병합을 막고 어떤 것이 장식인지 아무도 모르는 경우
• 커버리지, 성능, 접근성 숫자가 PR마다 논쟁되지만 한 번에 결정되지 않는 경우
• /build auto나 자율 루프를 실행하려고 하는데, main 브랜치로 가는 유일한 장애물이 에이전트가 직접 작성한 테스트 스위트뿐인 경우

사용하지 말아야 할 경우:

• 프로젝트에 이미 CONSTRAINTS.md가 있고 사용자가 변경하지 않는다면, 그것을 읽고 따르십시오. 이 스킬을 적용하지 마십시오.
• 일회성 스크립트, 스파이크, 프로토타입
• 사용자가 지금 당장 코드 리뷰(code-review-and-quality)나 CI 파이프라인(ci-cd-and-automation)을 원하는 경우
• 수명이 2주 정도로 예상되는 제품-시장 적합성(PMF) 이전 코드

제약 조건 로딩

인터뷰는 실제 사용자가 필요합니다. CI, /loop, 자율 실행과 같은 비대화형 환경에서는 실행하지 마십시오. 제약 조건이 없고 이러한 환경에 있다면, 아래 '최소 기준(Floor)'을 적용하고, 그렇게 했다는 점을 기록한 후, 나머지는 사람에게 플래그를 남기십시오.

프로세스

1단계: 묻기 전에 먼저 확인하라

읽을 수 있는 것을 묻지 마십시오. 첫 번째 질문 전에 다음 정보를 수집하십시오:

항목	찾을 위치
언어 및 스택	package.json, pyproject.toml, go.mod, Cargo.toml
테스트 러너	dev dependencies, test 스크립트, 기존 테스트 파일
기존 린터	eslint.config.*, biome.json, .ruff.toml
현재 커버리지	coverage/ 출력, 또는 한 번 실행
CI	.github/workflows/, .gitlab-ci.yml
에이전트 환경	.claude/, .codex/, AGENTS.md

찾은 내용을 두 줄로 보고하고, 남은 것에 대해서만 질문하십시오.

2단계: 각각 기본값이 있는 네 가지 질문

interview-me 스킬의 '한 번에 하나의 질문' 방식을 따르되, 한 가지 변경 사항이 있습니다: 여기 모든 질문에는 기본값이 있으므로 "모르겠습니다"라는 답변만으로도 작동하는 설정이 만들어집니다.

Q1: 최소 기준 외에, 다음 중 어떤 것을 적용하시겠습니까?
    (a) 새 코드에 대한 테스트 커버리지
    (b) 보안 스캐닝
    (c) 성능 예산
    (d) 접근성
    (e) 아키텍처 경계
예상: (a) 및 (b) — 이미 테스트 러너가 있고 사용자 입력을 처리하고 있습니다.
확실하지 않을 경우 기본값: (a) 및 (b).
각 선택의 비용을 설명하십시오: (c) 및 (d)는 실행 중인 URL이 필요하고, (e)는 규칙 파일 작성이 필요합니다.

Q2: 에이전트가 작업 중일 때 검사가 실패하면, 차단(block)해야 할까요, 경고(warn)만 해야 할까요?
예상: 차단. 무인 에이전트를 실행 중이고, 아무도 읽지 않는 경고는 경고의 의미가 없습니다.
확실하지 않을 경우 기본값: 최소 기준(Floor)은 차단, 나머지는 처음 2주 동안 경고.

Q3: 목표 숫자가 있으신가요, 아니면 현재 상태를 측정하여 그 선을 유지할까요?
예상: 측정. 대부분의 팀은 숫자가 없고, 임의로 만든 숫자는 무시됩니다.
확실하지 않을 경우 기본값: 측정 후 유지. 아래 "래칫(Ratchets)" 참조.

Q4: 에이전트가 작업을 넘기기 전에 용납할 수 있는 가장 느린 검사 시간은 얼마입니까?
예상: 약 90초. 더 길면 실행을 중단할 것입니다.
확실하지 않을 경우 기본값: 작업 종료 시 90초, CI에서는 무제한.

네 가지에서 멈추십시오. 열두 개의 질문으로 구성된 인테이크는 아무도 이해하지 못하는 설정과 시작을 후회하는 사용자를 만듭니다.

3단계: CONSTRAINTS.md 작성

리포지토리 루트에 하나의 파일을 만듭니다. 모든 에이전트와 모든 환경에서 읽을 수 있으며, 이 파일의 변경 사항은 리뷰에서 적절하게 표시됩니다.

# 제약 조건 (Constraints)

최종 검토: 2026-08-08, @addy

## 최소 기준 (항상 적용, 설정 불필요)

- 새로운 억제 주석 금지: `@ts-ignore`, `eslint-disable`, `# noqa`, `# type: ignore`
- 구현되지 않은 스텁 금지: `throw new Error("Not implemented")`, 빈 `catch {}`
- 커밋 메시지에 이유 없이 테스트 건너뛰기 또는 삭제 금지
- 소스 코드에 비밀 정보 금지
- 변경 사항을 통과시키기 위해 이 파일을 약화시키지 않음

## 숫자로 적용됨

| 차원 | 규칙 | 검사 도구 | 실행 시점 |
|-----------|------|-----------|---------|
| 타입 | 타입 오류 0개 | `tsc --noEmit` | 모든 편집 시 |
| 린트 | 설정 파일 기준 오류 0개 | `biome check` | 모든 편집 시 |
| 비밀 정보 | 소스 내 비밀 정보 없음 | `gitleaks detect --redact` | 모든 편집 시 |
| 커버리지 | 변경된 라인 ≥ 80% 커버 | `vitest run --coverage` + `git diff` | 작업 종료, CI |
| 보안: 코드 | 높은 수준 발견 사항 없음 | `semgrep scan --config p/default` | CI |
| 보안: 의존성 | 높음 이상 수준 없음 | `osv-scanner scan source -r .` | CI |
| 접근성 | 치명적 또는 심각 오류 0개 | `axe $PREVIEW_URL --tags wcag2a,wcag2aa,wcag21aa` | 프리뷰 배포 시 |
| 성능 | LCP ≤ 2500ms, CLS ≤ 0.1 | `lighthouse $PREVIEW_URL --output=json` | 프리뷰 배포 시 |

모든 행은 결과를 생성하는 명령어를 명시합니다. 이 열에 숫자와 명령어가 없는 차원은 제약 조건이 아니라 포부에 불과합니다.

## 측정됨, 아직 적용되지 않음

| 지표 | 현재 | 방향 |
|--------|-------|-----------|
| 프로젝트 커버리지 | 62.4% | 떨어지면 안 됨 |
| 번들 크기 (main) | 184 kB | 증가하면 안 됨 |

## 예외

| ID | 규칙 | 경로 | 이유 | 소유자 | 만료일 |
|----|------|------|--------|-------|---------|
| W1 | `no-explicit-any` | `src/legacy/**` | ENG-441에서 재작성 추적 중 | @addy | 2026-11-01 |

그런 다음 AGENTS.md와 CLAUDE.md에 한 줄을 추가하십시오: 코드를 작성하기 전에 CONSTRAINTS.md를 읽으십시오. 변경 사항을 통과시키기 위해 이 파일을 약화시키지 마십시오.

4단계: 각 차원에 필요한 도구 설치

차원을 선택한다는 것은 무언가를 설치한다는 의미입니다. 숫자만 제공하고 구현 메커니즘 없이 사용자를 방치하지 마십시오. 또한 사실상 표준(de facto)인 도구가 있다면 직접 검사기를 만들지 마십시오. 나열된 도구들은 그 규칙 형식과 임계값이 생태계의 다른 모든 것들이 목표로 하는 것이기 때문에 선택되었으며, 팀의 기존 설정이 계속 작동합니다.

차원	도구	설치	실행	게이트 조건
타입 (TS)	tsc	이미 있음	tsc --noEmit	모든 오류
타입 (Python)	mypy	pip install mypy	mypy .	모든 오류
린트	기존 설정	이미 있음	eslint . / biome check / ruff check	모든 오류
커버리지 (JS)	테스트 러너	이미 있음	vitest run --coverage (또는 jest --coverage)	변경된 라인의 커버리지
커버리지 (Python)	pytest-cov	pip install pytest-cov	pytest --cov --cov-report=lcov	동일
보안: 코드	Semgrep	pipx install semgrep	semgrep scan --config p/default --config p/owasp-top-ten	모든 높은 수준 발견 사항
보안: 비밀 정보	gitleaks	brew install gitleaks	gitleaks detect --redact --no-banner	모든 발견 사항
보안: 의존성	osv-scanner	brew install osv-scanner	osv-scanner scan source -r .	높음 이상
성능: 페이지	Lighthouse	npm i -D lighthouse	lighthouse $URL --output=json --quiet	LCP, CLS, 성능 점수
성능: 번들	size-limit	npm i -D size-limit	size-limit --json	항목별 바이트 예산
접근성	axe-core	npm i -D @axe-core/cli	axe $URL --tags wcag2a,wcag2aa,wcag21aa	치명적 또는 심각 오류 0개
아키텍처	dependency-cruiser	npm i -D dependency-cruiser	depcruise --validate src	모든 위반
단언문 품질	Stryker	npm i -D @stryker-mutator/core	stryker run --mutate <변경된 파일>	변형 점수

건너뛰면 문제가 생길 수 있는 다섯 가지 사항:

1. gitleaks의 --redact는 선택 사항이 아닙니다. 이것 없이는 일치된 비밀 정보가 에이전트의 기록에 그대로 남아 유출된 키가 로그, 요약 또는 커밋 메시지에 남게 됩니다. 규칙과 위치를 보고하고, 값은 절대 보고하지 마십시오.
2. Lighthouse와 axe는 URL이 필요합니다. 실행 중인 앱에서만 작동하므로, 런타임 단계에서 프리뷰 배포 또는 먼저 시작한 로컬 서버를 대상으로 해야 합니다. 프로젝트에 CLI, 라이브러리, 데스크톱 앱과 같이 실행 가능한 URL이 없다면, 그렇게 말하고 실행할 수 없는 검사를 발명하지 말고 해당 차원을 제거하십시오.
3. 비용이 많이 드는 검사는 diff로 범위를 제한하십시오. stryker run --mutate를 전체 리포지토리에 대해 실행하면 몇 시간이 걸려 결국 꺼지게 됩니다. 변경 사항이 있는 파일에 대해서만 실행하면 1분 미만이 소요됩니다. Semgrep도 마찬가지로 경로 목록을 받습니다.
4. 커버리지에 두 번째 테스트 실행이 필요하지 않습니다. 스위트가 이미 작성하는 lcov 파일을 읽고 git diff와 교차 참조하십시오. 숫자를 얻기 위해 스위트를 두 번 실행하는 것은 사람들이 싫어하게 만드는 가장 빠른 방법입니다.
5. Semgrep의 레지스트리 규칙은 무료로 실행할 수 있습니다. 재배포하기 전에 라이선스를 확인하십시오. 법무팀에서 문제가 된다면, 동일한 규칙 형식과 JSON 출력을 가진 드롭인 포크인 opengrep을 사용할 수 있습니다.

각 도구를 프로젝트의 자체 스크립트에 추가하여 에이전트 없이도 재현 가능하게 만드십시오:

{
  "scripts": {
    "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner",
    "check:task": "npm run check:fast && vitest run --coverage",
    "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ."
  }
}

이 매핑은 도구 자체보다 더 중요합니다. check:fast는 편집 후 실행되고, check:task는 에이전트가 작업이 완료되었다고 생각할 때 실행되며, check:full은 CI에서 실행됩니다.

명령어는 이제 CONSTRAINTS.md의 Checked by 열과 이 스크립트, 두 곳에 존재합니다. CONSTRAINTS.md가 표준 출처입니다: 각 명령어와 함께 이유를 제공하고 리뷰에 표시됩니다. 스크립트는 편의를 위한 래퍼이며 CONSTRAINTS.md를 반영해야 합니다. 만약 차이가 발생하면 CONSTRAINTS.md가 우선합니다.

5단계: 라이프사이클에 연결

가장 큰 실수는 모든 것을 모든 곳에서 실행하는 것입니다. 에이전트를 지연시키는 검사는 결국 꺼지고, 사람들이 꺼버린 게이트는 게이트가 없는 것보다 더 나쁩니다. 왜냐하면 기준이 여전히 존재하는 것처럼 보이기 때문입니다.

단계	명령어	실행 내용	예산
BUILD	/build	타입, 린트, 비밀 정보, 최소 기준	5초 미만, 변경된 파일만
VERIFY	/test	관련 테스트, 변경된 라인의 커버리지	90초 미만
REVIEW	/review	모든 것, 아래 가드 포함	수분
SHIP	/ship	방향 검사, 회귀 없음	CI

이를 허용 가능하게 만드는 두 가지 규칙:

1. diff로 범위를 제한하십시오. 전체 리포지토리가 아니라 이 변경 사항이 건드린 라인만 확인하십시오. 변경된 라인의 커버리지는 에이전트가 움직일 수 있는 숫자입니다. 프로젝트 커버리지는 상속받은 숫자입니다.
2. 비용이 배치를 결정합니다. 몇 초가 넘는 것은 편집 루프에서 제외하십시오. 전체 리포지토리에 대한 변형 테스트는 몇 시간이 걸리지만, 변경 사항이 있는 파일에 대해서는 1분 미만이 소요됩니다. 이것이 사람들이 실행하는 검사와 실행하지 않는 검사의 차이입니다.

6단계: 기준 자체 보호

에이전트가 코드와 검사를 모두 작성한다면 검사는 아무것도 증명하지 못한다는 지적이 있을 수 있습니다. 절반은 맞고, 이를 염두에 두고 설계해야 합니다.

에이전트는 교묘한 허점을 만들지 않습니다. 빨간 체크를 만나면 녹색으로 가는 가장 저렴한 경로를 택합니다. 리뷰 시간에 diff에서 다음 다섯 가지 움직임을 주시하십시오:

1. 임계값이 변경되었습니다. 예산이 낮아졌고, 심각도가 낮아졌으며, 빠른 단계에서 검사가 제거되었습니다. CONSTRAINTS.md를 분기 시점의 상태와 비교하십시오.
2. 테스트가 쉬워졌습니다. .skip 추가, 테스트 파일 삭제, 유지된 테스트에서 단언문 제거.
3. 검사기가 침묵되었습니다. 새로운 @ts-ignore 또는 eslint-disable. 특히 주의해야 할 네 가지 억제는 다음과 같습니다: istanbul ignore는 코드를 테스트 대상에서 제외시키고, Stryker disable은 살아남은 변종을 숨기며, nosemgrep과 gitleaks:allow는 보안 발견 사항에 대해 동일한 역할을 합니다.
4. 작업이 완료되지 않았습니다. 예외를 던지는 스텁, 실패를 침묵으로 바꾸는 빈 catch, 구현이 있어야 할 자리에 있는 TODO.
5. 예외가 나타났습니다. 아무도 논의하지 않은 Exceptions 테이블의 새 행.

이러한 것들을 감지하는 데 git diff 이상의 도구는 필요하지 않습니다. 기준을 강화하는 것은 조용히 이루어져야 합니다. 기준을 완화하는 것은 크게 알려져야 합니다.

번호가 매겨진 차원과 달리, 최소 기준(Floor)에는 자체적인 사실상 표준(de facto) 도구가 없으므로, 이를 시행하라는 지시를 받은 에이전트는 종종 처음부터 검사기를 작성하게 되고, 두 에이전트는 서로 다른 검사기를 작성합니다. 이 다섯 가지 검사의 참조 구현은 이 스킬과 함께 references/floor-guard.md에 제공됩니다 (diff 범위, 종료 코드 0/1/2, 생태계별 적응 가능 패턴). 매번 새로 만들기보다는 이를 적용하십시오. 모든 차원이 사실상 표준 도구를 명명하는 것과 같은 이유입니다: 실행과 스택에 걸쳐 메커니즘이 동일하도록 보장하기 위해서입니다.

모든 검사가 동일하게 순환적(circular)인 것은 아닙니다. 한 가지 질문으로 순위를 매기십시오: 에이전트가 작동하지 않는 코드를 작성하여 이 검사를 통과할 수 있습니까?

• 외부(External) — axe-core는 WCAG를 인코딩하고, osv-scanner는 취약점 데이터베이스를 읽으며, Lighthouse는 실제 브라우저를 측정합니다. 에이전트가 이의를 제기할 수 없습니다.
• 프로젝트(Project) — 당신의 린트 규칙, 레이어 경계. 사람이 파일을 소유합니다.
• 스위트(Suite) — 당신 자신의 테스트. 가장 유용하며, 유일하게 진정으로 순환적인 것입니다.

기준(Bar)은 모든 외부 및 프로젝트 검사를 통과하고 스위트 검사도 통과하는 것 이상이어야 합니다. 최소 기준은 이러한 모든 범주에 걸쳐 있으며 특히 2번과 4번 항목은 스위트 검사에 중점을 둡니다.

7단계: 래칫(Ratchets) — 3단계 Q3을 위한 것

Q3에서 "측정 후 유지"를 선택했다면 다음을 따르십시오:

1. 오늘 값을 측정하십시오 (npm run check:task 또는 동등한 명령)
2. 측정된 값, 아직 적용되지 않음 섹션에 추가하십시오
3. CI에서 각 실행마다 현재 값이 섹션의 값보다 낮지 않은지 확인하는 작업을 추가하십시오
4. 2주 후에 사용자에게 이 숫자 중 일부를 강제 적용(적용됨 섹션으로 이동)할지 물어보십시오

래칫의 목적은 작업을 시작하는 것을 막지 않으면서 퇴보를 방지하는 것입니다. 막 시작한 프로젝트에 80% 커버리지 게이트를 두는 것은 모든 사람이 무시하는 설정을 만듭니다. 오늘의 62%를 래칫으로 설정하면 다음 주에 갑자기 45%로 떨어지는 것을 방지할 수 있습니다.

참조 및 추가 읽을거리

• CONSTRAINTS.md 템플릿 — 모든 차원의 전체 예시
• 최소 기준(Floor Guard) 구현 — 범위가 지정된 5가지 검사, 종료 코드
• 에이전트 설정 (CLAUDE.md) — AGENTS.md / CLAUDE.md에 추가할 내용
• CI 통합 예시 — GitHub Actions, GitLab CI, 로컬 후크
• Constraint-Driven Development 소개 — 원본 게시물

전문 용어

• 최소 기준 (Floor): 모든 프로젝트, 환경 및 언어에 적용되는 최소한의 합의 사항입니다. 도구 설치가 필요하지 않으며 주로 diff 검사(@ts-ignore 등)에 의존합니다.
• 래칫 (Ratchets): 임의의 목표가 아닌, 측정된 현재 값에 대해 회귀를 방지하는 추세선입니다.
• 차원 (Dimension): 코드 품질의 측정 가능한 측면(예: 유형, 린트, 보안 등). 각 차원에는 도구, 명령어, 게이트 조건이 필요합니다.