Verdent Docs
에이전트 및 규칙

규칙 시스템과 동작 가이드

규칙 시스템으로 Verdent의 동작 제어하기

규칙 파일은 코딩 세션 중 Verdent이 어떻게 동작하고 응답할지 정의하는 Markdown 문서입니다. AI 에이전트의 동작, 출력 형식, 의사결정, 프로젝트 표준 준수를 안내합니다.

목적:
규칙을 사용하면 코드나 설정을 변경하지 않고도 Verdent의 동작을 맞춤 설정할 수 있습니다. 세션 간에 유지되는 코딩 규약, 선호 패턴, 커뮤니케이션 스타일, 작업 실행 방식을 정합니다.

규칙 작동 방식:
Verdent은 대화 중 규칙 파일을 계속 참조하며, 코드 생성, 분석, 문서화, 의사결정에 가이드를 적용합니다. 규칙은 모든 에이전트 응답에 영향을 주어 사용자 선호와 일관되게 동작하도록 합니다.

세 가지 범주:

  • 전역 선호 설정 (VERDENT.md) - 개인 코딩 스타일, 언어 선호
  • 프로젝트별 표준 (AGENTS.md) - 팀 규약, 아키텍처 패턴
  • 플랜 맞춤 설정 (Plan.md) - Plan Mode 출력 형식과 내용

규칙 우선순위:
규칙이 충돌하면 Verdent은 다음 우선순위를 적용합니다: AGENTS.md (가장 높음) → VERDENT.md (중간) → 기본값 (가장 낮음)


사용자 규칙 (VERDENT.md)

VERDENT.md는 모든 프로젝트와 세션에 적용되는 전역 선호 설정을 정의합니다. 개인 코딩 스타일, 선호 도구, 커뮤니케이션 선호, 기본 동작을 정합니다.

위치와 범위

파일 위치: ~/.verdent/VERDENT.md

범위: 모든 프로젝트에 전역 적용

접근:

  • Settings → Rules → User Rules
  • ~/.verdent/VERDENT.md에서 직접 파일 편집

변경 사항 적용 시점:
규칙은 새 대화에 즉시 적용되며, 현재 대화의 응답에도 영향을 줍니다.


사용 사례

코딩 선호

  • 들여쓰기 스타일(공백 2칸, 공백 4칸, 탭)
  • 이름 지정 규약(camelCase, snake_case, PascalCase)
  • 선호하는 언어 기능(ES6+, TypeScript strict mode, type hints)

모든 프로젝트에 적용되는 개인 코딩 스타일과 규약을 정의합니다.

출력 언어

  • 기본 응답 언어(예: "항상 스페인어로 응답")
  • 기술 용어 처리("프랑스어 대응어가 없으면 영어 용어 사용")

Verdent이 응답과 설명에 사용하는 언어를 제어합니다.

코드 주석

  • 선호하는 상세 수준("상세한 주석" 또는 "최소한의 주석만")
  • 주석 언어("프랑스어로 주석 작성")

코드에 얼마나 많은 주석을 어떤 언어로 작성할지 지정합니다.

문서화 스타일

  • 코드를 문서화하는 방식(JSDoc, TSDoc, docstrings)
  • 문서에 사용 예시 포함

API 문서와 코드 문서화 형식의 표준을 설정합니다.

커뮤니케이션

  • 응답의 톤과 상세도("간단한 설명" 또는 "상세한 설명")
  • 설명 방식("코드를 먼저 보여주고 나중에 설명")

Verdent이 사용자와 소통하고 정보를 제시하는 방식을 맞춤 설정합니다.


형식과 문법

VERDENT.md는 글머리 기호나 번호 목록을 사용하는 일반 Markdown 형식을 사용합니다.

구조:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

작성 스타일:

  • 명확하고 지시적인 표현을 사용합니다("항상 ... 사용", "... 선호", "절대 ... 하지 않음")
  • 헤더로 논리적 섹션을 구성합니다
  • 개별 규칙은 글머리 기호로 작성합니다
  • 원하는 동작을 구체적으로 명시합니다

개발자 유형별 예시

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

적용:
Verdent에게 새 React 컴포넌트를 만들도록 요청하면 자동으로 다음을 수행합니다.

  • strict mode로 TypeScript 사용
  • named export 생성(default 아님)
  • @param/@returns 태그가 있는 TSDoc 주석 추가
  • 범주별로 import 정리
# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

적용:
Verdent에게 데이터 분석 코드를 작성하도록 요청하면 다음을 수행합니다.

  • 데이터 작업에 pandas 사용
  • 모든 함수에 type hints 포함
  • 변환 후 DataFrame.head()와 shape 표시
  • 데이터 가정을 문서화하는 인라인 주석 추가
# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

적용:
Verdent은 다음을 수행합니다.

  • ES6+ 문법으로 최신 JavaScript 작성
  • promise 체인 대신 async/await 사용
  • 80% 커버리지를 목표로 Jest 테스트 생성
  • 성능과 보안 우려를 선제적으로 식별
# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

적용:
모든 Verdent 응답은 프랑스어로 작성되며, 적절한 경우 기술 용어는 영어로 유지됩니다. 코드 주석과 문서는 사용자의 언어 선호를 따릅니다.

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

적용:
Verdent은 다음을 수행합니다.

  • 간결하고 자체 설명적인 코드 생성
  • 함수를 20줄 미만으로 유지
  • 코드를 보여준 뒤 간단한 설명 제공
  • 사용자가 명시적으로 요청하지 않는 한 장황한 주석 피하기

생성 및 편집 방법

대부분의 사용자에게 권장

  1. Verdent 상단 바에서 Settings 버튼을 선택합니다
  2. 드롭다운에서 Rules를 선택합니다
  3. User Rules를 선택합니다
  4. 파일이 VS Code 편집기에서 열립니다
  5. Markdown 형식으로 편집합니다
  6. 파일을 저장합니다(Cmd+S / Ctrl+S)

이 방법은 파일 위치를 자동으로 찾아 기본 편집기에서 엽니다.

고급 사용자에게 권장

  1. ~/.verdent/VERDENT.md로 이동합니다
  2. 원하는 텍스트 편집기에서 엽니다
  3. Markdown 내용을 편집합니다
  4. 변경 사항을 저장합니다

설정 파일을 직접 다루는 것을 선호한다면 이 방법이 더 빠릅니다.


프로젝트 규칙 (AGENTS.md)

AGENTS.md는 현재 프로젝트에서 에이전트 동작을 제어하는 프로젝트별 규칙을 정의합니다. 프로젝트에 특화된 팀 코딩 표준, 아키텍처 패턴, 테스트 요구사항, 개발 워크플로를 정합니다.

위치와 범위

파일 위치: 프로젝트 루트 디렉터리

범위: 현재 프로젝트에만 적용

버전 관리: 팀 전체 공유를 위해 git에 커밋할 수 있음

접근:

  • Settings → Rules → Project Rules
  • <project-root>/AGENTS.md에서 직접 편집

사용 사례

팀 규약

모든 팀원이 따르는 공유 코딩 표준:

  • 팀 전체에서 일관된 들여쓰기
  • 컴포넌트/함수 이름 지정 규약
  • 파일 구성 패턴

전체 개발 팀에서 일관된 코딩 스타일을 적용합니다.

아키텍처 패턴

프로젝트별 설계 패턴:

  • MVC, microservices, monorepo 구조
  • 상태 관리 방식(Redux, Context, Zustand)
  • API 설계 패턴(REST, GraphQL)

프로젝트의 아키텍처 결정과 패턴을 정의합니다.

테스트 요구사항

기대하는 테스트 커버리지와 프레임워크:

  • 최소 커버리지 기준(80%, 90%)
  • 테스트 프레임워크(Jest, pytest, Vitest)
  • 테스트 파일 이름 지정 규약

프로젝트의 테스트 표준과 품질 게이트를 정합니다.

개발 워크플로

빌드 명령, 배포 절차, PR 가이드라인:

  • 테스트 실행 방법(pnpm test, npm run test)
  • 특정 패키지의 빌드 명령
  • PR 제목 형식 요구사항

팀 워크플로와 개발 절차를 문서화합니다.

기술 제약

승인된 라이브러리와 프레임워크 버전:

  • 허용되는 의존성
  • 프레임워크 버전 요구사항
  • 플랫폼 지원(iOS 14+, Android API 26+)

기술 스택 선택을 제어하고 일관성을 유지합니다.

팀 협업:
AGENTS.md는 프로젝트 루트에 저장되며 버전 관리에 커밋할 수 있어, 모든 팀원이 일관된 에이전트 동작으로 작업할 수 있습니다.

모든 팀원이 일관된 AI 동작을 사용하도록 AGENTS.md를 버전 관리로 팀과 공유하세요.


형식과 문법

AGENTS.md는 VERDENT.md와 비슷하게 구조화된 섹션과 글머리 기호를 사용하는 Markdown 형식을 사용하지만, 프로젝트별 요구사항에 초점을 둡니다.

구조:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

작성 스타일:

  • 명령형의 지시적인 표현
  • 워크플로 영역별 구성(개발, 테스트, 배포)
  • 구체적인 명령과 절차
  • 개인 선호가 아닌 팀 전체 표준

프로젝트 유형별 예시

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

적용:
이 monorepo에서 작업할 때 Verdent은 다음을 수행합니다.

  • 탐색과 테스트에 turbo 명령 사용
  • 프로젝트 이름 접두사를 붙여 PR 제목 형식 지정
  • 커밋을 제안하기 전에 lint와 test 명령 실행
# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

적용:
Verdent이 만드는 모든 React 컴포넌트는 다음을 따릅니다.

  • hooks를 사용하는 함수형 컴포넌트 사용
  • TypeScript 인터페이스 포함
  • 올바른 디렉터리에 배치
  • 80% 커버리지를 목표로 Jest 테스트 포함
# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

적용:
API 엔드포인트를 만들 때 Verdent은 다음을 수행합니다.

  • 입력 검증 자동 추가
  • 데이터베이스 작업에 매개변수화된 쿼리 사용
  • 성공과 오류 케이스 모두에 대한 테스트 생성
  • 민감한 데이터 로깅 피하기
# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

적용:
모바일 앱 코드는 다음을 따릅니다.

  • 최소 플랫폼 버전 지원
  • 상태 관리에 Redux Toolkit 사용
  • 이미지를 WebP 형식으로 최적화
  • 긴 목록 성능을 위해 FlatList 사용
# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

적용:
Django 코드는 다음을 따릅니다.

  • class-based views 사용
  • raw SQL 대신 Django ORM 사용
  • Factory Boy fixtures로 pytest 테스트 생성
  • 90% 이상의 테스트 커버리지 목표

VERDENT.md와의 차이점

범위:

  • VERDENT.md: 모든 프로젝트에 적용되는 개인 선호
  • AGENTS.md: 특정 프로젝트에만 적용되는 팀 표준

우선순위:

  • AGENTS.md: 더 높은 우선순위 - 프로젝트 일관성을 위해 user_rules를 재정의
  • VERDENT.md: 더 낮은 우선순위 - 충돌하는 프로젝트 규칙이 없을 때 적용

내용 초점:

  • VERDENT.md: 개인 코딩 스타일, 커뮤니케이션 선호, 개인 도구
  • AGENTS.md: 팀 규약, 프로젝트 아키텍처, 공유 워크플로, 기술 스택

버전 관리:

  • VERDENT.md: 공유하지 않음 - 개인 머신에 유지
  • AGENTS.md: git에 커밋 - 전체 팀과 공유

저장 위치:

  • VERDENT.md: ~/.verdent/VERDENT.md (전역)
  • AGENTS.md: 프로젝트 루트 디렉터리(프로젝트별)

충돌 해결 예시:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

언제 무엇을 사용할지:

  • VERDENT.md: 모든 프로젝트에 적용하고 싶은 개인 선호
  • AGENTS.md: 이 프로젝트에서 전체 팀이 따라야 하는 표준

플랜 규칙 (Plan.md)

Plan.md는 Plan Mode에서 생성되는 플랜의 내용과 형식을 맞춤 설정합니다. 플랜의 상세 수준, 포함할 섹션, 형식 선호, 표시할 정보를 제어합니다.

위치와 범위

파일 위치: ~/.verdent/plan_settings.json

범위: 모든 프로젝트에 전역 적용

적용: 플랜을 생성할 때 Plan Mode 중에만 적용

접근:

  • Settings → Rules → Plan Rules
  • ~/.verdent/plan_settings.json에서 직접 파일 편집

사용 사례

플랜 구조

포함할 섹션 정의:

  • 요약, 사전 요구사항, 단계, 검증
  • 위험 평가, 롤백 절차
  • 시간 추정, 핵심 경로

모든 플랜에 어떤 섹션과 정보가 표시될지 제어합니다.

상세 수준

세분화 수준 제어:

  • 상위 수준 개요(각 1~2시간 단위의 단계)
  • 상세 구현 단계(15~30분 단위의 작업)
  • 함수 수준 세부사항(시그니처, 파일 경로)

구현 플랜이 얼마나 세분화되고 구체적이어야 하는지 조정합니다.

형식 선호

표시 방식 선택:

  • 번호 목록 또는 글머리 기호
  • 코드 스니펫 또는 설명
  • 다이어그램(문장으로 설명)

플랜 정보의 형식과 표시 방식을 맞춤 설정합니다.

정보 포함

추가 요소 지정:

  • 인라인 시간 추정
  • 위험 수준(낮음/중간/높음)
  • 팀 협업을 위한 역할 배정
  • 테스트 요구사항 강조

플랜을 더 실행 가능하게 만들기 위해 컨텍스트와 메타데이터를 추가합니다.


형식과 문법

Plan.md는 원하는 플랜 구조와 내용을 설명하는 섹션이 있는 Markdown 형식을 사용합니다.

구조:


---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

플래닝 스타일별 예시

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

적용:
플랜에는 다음이 포함됩니다.

  • 맨 위의 실행 요약
  • 20~30분 단위의 작업 분해
  • src/components/Auth/Login.tsx 같은 구체적인 파일 경로
  • async function authenticateUser(credentials: UserCredentials): Promise<AuthResult> 같은 함수 시그니처
  • 테스트와 롤백 절차
---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

적용:
플랜은 상위 수준으로 작성되며 다음에 집중합니다.

  • 3~5개의 주요 단계로 구성된 전략적 접근
  • 구현 세부사항보다 "왜"에 대한 설명
  • 결정 지점과 트레이드오프
  • 구체적인 구현 없이 성공 기준 제시
---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

적용:
플랜에는 다음이 포함됩니다.

  • 각 단계의 시간 추정: "인증 미들웨어 생성(45분)"
  • 총 소요 시간: "예상 총계: 6시간"
  • 병렬 작업 표시: "3단계와 병렬로 진행 가능"
  • 차단 작업을 보여주기 위한 핵심 경로 굵게 표시
---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

적용:
각 단계에는 다음이 포함됩니다.

  • 위험 평가: "위험: 높음(프로덕션 데이터베이스 마이그레이션)"
  • 완화: "먼저 staging에서 마이그레이션을 실행하고 테스트 쿼리로 검증"
  • 롤백: "문제가 발생하면 down script로 마이그레이션 되돌리기"
---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

적용:
플랜은 다음을 지정합니다.

  • "Backend API (Backend Team): 인증 엔드포인트 생성"
  • "연동 지점: 프런트엔드 팀은 백엔드의 API 사양을 기다림"
  • "리뷰 필요: 병합 전 보안 팀 리뷰"

플랜 규칙은 언제 적용되나요?

플랜 규칙 적용:

  • 시점: 플랜을 생성할 때 Plan Mode 중에만 적용
  • 범위: 코드 생성이 아니라 플랜 형식과 내용을 제어
  • 독립성: VERDENT.md 또는 AGENTS.md와 충돌하지 않음

다른 규칙 유형 적용:

  • VERDENT.md: 모든 모드(Agent, Plan, Chat)에 계속 적용
  • AGENTS.md: 프로젝트별 동작을 위해 모든 모드에 계속 적용

상호작용 예시:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

모드별 동작:

  • Agent Mode: VERDENT.md + AGENTS.md 적용(plan_rules.md 없음)
  • Plan Mode: VERDENT.md + AGENTS.md + Plan.md 모두 적용
  • Chat Mode: VERDENT.md + AGENTS.md 적용(Plan.md 없음)

규칙 우선순위와 충돌 해결

규칙이 충돌하면 Verdent은 일관된 동작을 보장하기 위해 우선순위를 적용합니다.

우선순위 순서

1. 프로젝트 규칙 (AGENTS.md) - 가장 높은 우선순위
프로젝트별 규칙은 전역 선호를 재정의합니다. 일관성을 위해 팀 표준이 개인 선호보다 우선합니다.

2. 사용자 규칙 (VERDENT.md) - 중간 우선순위
충돌하는 프로젝트별 규칙이 없을 때 전역 선호가 적용됩니다.

3. 기본 동작 - 가장 낮은 우선순위
규칙이 지정되지 않은 경우 Verdent의 내장 기본값이 적용됩니다.

충돌 해결 예시:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)

플랜 규칙: Plan.md는 Plan Mode 중에 독립적으로 적용되며 사용자/프로젝트 규칙과 충돌하지 않습니다. Plan.md는 플랜 형식을 제어하고, VERDENT.md와 AGENTS.md는 플랜 안의 코드 스타일을 제어합니다.

플랜 규칙은 Plan Mode 출력 형식에만 영향을 줍니다. Verdent이 솔루션을 분석하거나 구현하는 방식은 바꾸지 않습니다.

우선순위를 기억하세요: AGENTS.md(가장 높음) → VERDENT.md(중간) → 기본값(가장 낮음). 충돌이 발생하면 프로젝트 규칙이 항상 우선합니다.

자세한 충돌 해결 알고리즘, 충돌 중 적용 중인 규칙을 확인하는 메커니즘, 임시 규칙 중지를 위한 재정의 메커니즘은 현재 개발 중입니다.


규칙 충돌 문제 해결

규칙과 모순되는 예상치 못한 동작이 보이면 다음 디버그 전략을 따르세요.

1단계: 충돌 식별

  1. 규칙과 모순되는 예상치 못한 동작을 확인합니다
  2. 해당 상황에 어떤 규칙이 적용될 수 있는지 확인합니다
  3. 규칙 파일 간의 모순을 찾습니다

2단계: 규칙 우선순위 확인

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

프로젝트 규칙은 개인 선호를 재정의합니다.

3단계: 격리해서 테스트

VERDENT.md 비활성화:
파일 이름을 임시로 바꾸거나 내용을 비운 뒤, 충돌이 해결되는지 테스트합니다

AGENTS.md 없이 테스트:
AGENTS.md가 없는 프로젝트에서 작업해 user_rules 동작을 격리합니다

새 대화:
대화 컨텍스트의 영향을 제거하기 위해 새 세션을 시작합니다


일반적인 충돌 시나리오

시나리오 1: 형식 충돌

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

시나리오 2: 같은 파일 안의 모순된 규칙

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

수정 예시:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

시나리오 3: 너무 모호한 규칙

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

디버그 전략

1. 명시적 테스트:
Verdent에게 "[특정 동작]에 대해 어떤 규칙을 따르고 있나요?"라고 묻습니다

예시:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

2. 점진적 구체화:
모호한 규칙에 구체성을 추가합니다

규칙 충돌을 디버그할 때는 규칙을 하나씩 임시로 비활성화하여 어떤 규칙이 예상치 못한 동작을 일으키는지 격리하세요.

이전:

- Use appropriate error handling

이후:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. 우선순위 표시:
협상할 수 없는 규칙에는 "CRITICAL:" 또는 "REQUIRED:"를 사용합니다

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

규칙 작성 모범 사례

구체적이고 지시적으로 작성하기:

  • 명확하고 명령형 표현을 사용합니다("항상 ... 사용", "절대 ... 하지 않음", "... 선호")
  • 모호한 표현을 피합니다("... 하려고 시도" → "항상 ...")
  • 원하지 않는 것이 아니라 원하는 것을 정확히 명시합니다

좋은 예:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

피해야 할 예:

- Try to use modern JavaScript features
- Add comments when necessary

논리적으로 구성하기:

  • 관련 규칙을 섹션 헤더 아래에 묶습니다
  • 관심사를 분리합니다(스타일, 테스트, 문서화, 보안)
  • 규칙 파일 전체에서 일관된 구조를 사용합니다

유지보수하기 쉽게 유지하기:

  • 간결한 규칙을 작성합니다(글머리 기호 하나에 개념 하나)
  • 프로젝트가 발전함에 따라 규칙을 검토하고 업데이트합니다
  • 오래된 규칙은 즉시 제거합니다

중요한 규칙 우선 배치하기:

  • 각 섹션에서 핵심 규칙을 먼저 배치합니다
  • 협상 불가능한 표준에는 강조를 사용합니다("NEVER commit credentials")
  • 버그나 보안 문제를 예방하는 규칙에 집중합니다

규칙 효과 테스트하기:

  • Verdent이 실제로 규칙을 따르는지 검증합니다
  • 새 대화를 시작해 규칙 적용을 테스트합니다
  • 실제 에이전트 동작을 바탕으로 규칙을 다듬습니다

상세함과 유연성의 균형 맞추기:

  • 너무 구체적 → 상황에 적응하지 못하는 경직된 동작
  • 너무 모호함 → 일관되지 않은 동작
  • 컨텍스트에 맞는 결정을 내릴 여지를 남기면서 명확한 가이드를 목표로 합니다

팀 고려사항(AGENTS.md):

  • 규칙 생성에 팀을 참여시킵니다
  • 직관적이지 않은 규칙의 근거를 문서화합니다
  • 팀 규칙은 개인 선호가 아니라 공유 표준에 집중하도록 유지합니다

함께 보기