0910 운영 자동화/AI 워크플로우 심화 (6/N): 프로젝트 지식베이스, AI 컨텍스트 관리와 규칙 자동 주입
✅ 1. AI 개발에서 컨텍스트가 중요한 이유
- AI/Codex가 코드를 잘 작성하려면 단순히 현재 파일만 알아서는 부족합니다.
- 프로젝트의 구조, 비즈니스 규칙, 금지 사항, API 계약, DB 정책, 권한 기준, 과거 장애까지 알아야 기존 코드와 맞는 결과를 만들 수 있습니다.
- 같은 모델이라도 어떤 컨텍스트를 주느냐에 따라 결과 품질 차이가 크게 납니다.
AI에게 코드만 전달
↓
현재 파일 기준으로 추측
↓
기존 프로젝트 규칙과 충돌 가능
프로젝트 Context 전달
↓
구조/규칙/과거 결정 이해
↓
기존 코드와 맞는 수정 가능성 증가➕ 1-1. 컨텍스트가 부족할 때 생기는 문제
Controller에 비즈니스 로직을 다시 넣음
Repository를 거치지 않고 Prisma 직접 호출
기존 PermissionCode 대신 새로운 role 조건 생성
기존 error response를 다른 형태로 변경
transaction 규칙을 무시
Soft Delete 조건 누락
이미 해결했던 장애 패턴을 다시 만듦- AI의 실수 중 상당수는 모델 성능보다 프로젝트 맥락 부족에서 발생합니다.
- 프로젝트의 암묵적인 규칙을 명시적인 지식으로 바꿔주는 것이 중요합니다.
✅ 2. 프로젝트 지식베이스란 무엇인가?
- 프로젝트 지식베이스는 개발자가 머릿속으로 알고 있는 규칙과 과거 결정을 AI도 이해할 수 있도록 문서화한 자료입니다.
- 단순 README보다 더 실무적인 개발 기준을 담습니다.
README:
프로젝트 소개
Architecture Docs:
시스템 구조
AI Knowledge Base:
AI가 작업할 때 반드시 알아야 할 규칙과 결정➕ 2-1. 지식베이스에 들어갈 정보
프로젝트 개요
기술 스택
모듈 구조
핵심 도메인
아키텍처 규칙
DB 설계 규칙
권한 정책
에러 응답 계약
보안 규칙
테스트 전략
자주 발생한 실수
과거 주요 결정- 중요한 것은 문서가 많아지는 것이 아니라 AI 작업에 필요한 정보가 정리되어 있는 것입니다.
✅ 3. 추천 docs/ai 구조
docs/
ai/
README.md
project-context.md
architecture.md
backend-rules.md
frontend-rules.md
database-rules.md
security-rules.md
testing-rules.md
api-contract.md
permissions.md
common-mistakes.md
decisions/
ADR-001-transaction-boundary.md
ADR-002-export-job.md
ADR-003-permission-model.md➕ 3-1. 역할
project-context.md:
프로젝트 전체 소개
architecture.md:
Controller/UseCase/Repository/Worker 구조
backend-rules.md:
NestJS 작업 규칙
database-rules.md:
Prisma/PostgreSQL 규칙
security-rules.md:
PII/Secret/운영 데이터 기준
common-mistakes.md:
AI가 과거 반복한 실수
decisions/:
왜 특정 구조를 선택했는지 기록- 이 폴더가 AI 작업의 “프로젝트 설명서” 역할을 하게 됩니다.
✅ 4. project-context.md
- AI가 처음 프로젝트를 봤을 때 반드시 알아야 할 최소 정보를 넣습니다.
# Project Context
## 프로젝트
온라인 휴대폰 판매몰
## 주요 사용자
- 고객
- 상담 관리자
- 운영 관리자
## 핵심 기능
- 상품/요금제 조회
- 상담 신청
- 관리자 상담 처리
- 상품/지원금 관리
- 유입 분석
- Excel Export
- 알림톡
- 관리자 권한
## Backend
- NestJS
- Prisma
- PostgreSQL
- AWS
## Frontend
- React
- TanStack Query
## 운영 특징
- 1인 개발/운영
- 고객 개인정보 존재
- 관리자 기능 비중이 높음
- 운영 중 변경 이력과 추적성이 중요함
## 핵심 원칙
- 중요한 상태 변경은 transaction 사용
- 외부 API를 transaction 안에서 호출하지 않음
- 개인정보를 로그에 남기지 않음
- 관리자 위험 기능은 Permission 검증 필요- AI에게 매번 프로젝트 전체를 설명하는 비용을 줄일 수 있습니다.
✅ 5. 아키텍처 규칙 문서
# Backend Architecture Rules
## Controller
- HTTP 요청/응답만 담당
- Prisma 직접 사용 금지
- 비즈니스 규칙 작성 금지
## Use Case
- 하나의 업무 흐름 담당
- Transaction Boundary 관리
- Repository와 Domain Service 조합
## Domain Service / Policy
- 상태 전이
- 중복 판단
- 세부 권한
- 비즈니스 규칙
## Repository
- Prisma DB 접근 담당
- 필요한 경우 TransactionClient 지원
## Adapter
- 외부 API 호출 담당
## Worker
- 오래 걸리는 작업과 재시도 처리➕ 5-1. 금지 규칙도 명확하게
금지:
Controller → Prisma 직접 호출
Use Case → axios 직접 호출
Repository → 관리자 권한 판단
Worker → 고객 전화번호 로그 출력- AI는 “해야 하는 것”뿐 아니라 “하면 안 되는 것”을 알려줄 때 더 안정적입니다.
✅ 6. DB 규칙 지식베이스
- Prisma/PostgreSQL은 변경 위험이 높으므로 별도 문서로 관리하는 것이 좋습니다.
# Database Rules
## Transaction
다음 작업은 같은 transaction:
- 상담 상태 변경
- 상담 상태 이력
- Audit Log
## Soft Delete
- 삭제 가능 도메인은 deletedAt 사용
- 고객 조회에서는 deletedAt=null 조건 유지
- 관리자 삭제 목록은 별도 Repository 메서드 사용
## 개인정보
- phoneNormalized를 API 응답에 노출하지 않음
- 전화번호 원본을 로그에 출력하지 않음
## Migration
- destructive migration 자동 적용 금지
- NOT NULL 추가 전 기존 데이터 검토
- 운영 migration은 사람이 승인➕ 6-1. AI가 자주 놓치는 내용
Soft Delete filter
snapshot column
unique constraint
transaction client 전달
migration backfill- 반복적으로 설명하는 DB 규칙은 반드시 지식베이스로 승격하는 것이 좋습니다.
✅ 7. API Contract 문서
- AI 리팩토링에서 가장 위험한 것 중 하나가 기존 API 응답 변경입니다.
- 기존 프론트와 연결되어 있으므로 기본 계약을 문서화하는 것이 좋습니다.
# API Contract
## Error Response
{
"success": false,
"error": {
"code": "...",
"message": "...",
"details": null
},
"requestId": "...",
"timestamp": "...",
"path": "..."
}
## Rules
- 별도 요구가 없으면 기존 field rename 금지
- 기존 field 삭제 금지
- status code 변경 시 명시적 검토 필요
- error.code 변경은 frontend 영향 확인 필요➕ 7-1. 목록 응답
data
meta.page
meta.limit
meta.total
meta.totalPages➕ 7-2. 중요 규칙
리팩토링:
API Contract 유지
API Contract 변경:
별도 Task로 수행- 구조 개선과 API 변경을 같은 작업에서 섞지 않는 것이 좋습니다.
✅ 8. Permission 지식베이스
# Permission Rules
## 기본 원칙
Role 이름보다 PermissionCode 기준으로 판단
## 주요 Permission
CONSULT_READ
CONSULT_DETAIL_READ
CONSULT_UPDATE_STATUS
CONSULT_EXPORT
PRODUCT_READ
PRODUCT_UPDATE
PRODUCT_PRICE_UPDATE
AUDIT_LOG_READ
EXPORT_JOB_DOWNLOAD
ADMIN_PERMISSION_MANAGE
## 규칙
- 프론트 메뉴 숨김은 UX
- 백엔드 PermissionGuard가 최종 검증
- Export 다운로드는 일반 조회 권한과 분리
- 관리자 권한 변경은 Audit Log 기록➕ 8-1. AI 작업 시 활용
Task:
상담 Excel Export 추가
자동 Context:
CONSULT_EXPORT Permission 필요
Audit Log 필요
파일 만료/다운로드 권한 필요- AI가 기존 권한 정책을 모르고 새 구조를 만드는 것을 막아줍니다.
✅ 9. Security Rules
- AI에게 가장 강하게 주입해야 하는 규칙 중 하나입니다.
# Security Rules
## AI에게 전달 금지
- 운영 고객 데이터
- DB Dump
- API Key
- JWT
- Authorization Header
- Cookie
- DATABASE_URL
## 로그 금지
- 전화번호 원본
- 상담 메모 전체
- accessToken
- refreshToken
- Secret
## 코드
- Secret 하드코딩 금지
- 환경값은 SSM/Config 사용
- 운영 DB 직접 수정 금지➕ 9-1. 절대 규칙
운영 Secret을 AI Prompt에 넣지 않는다.
실제 고객 데이터를 AI 테스트 데이터로 사용하지 않는다.
운영 DB dump를 분석 입력으로 사용하지 않는다.- 이 문서는 AI를 위한 규칙이면서 본인을 위한 체크리스트이기도 합니다.
✅ 10. common-mistakes.md
- AI가 한 번 실수한 것은 기록해두면 좋습니다.
- 같은 실수를 반복하면 프로젝트 규칙으로 승격합니다.
# Common AI Mistakes
## 1. Repository Transaction 누락
### 발생
Use Case에서 transaction을 열었지만 Repository가 기본 PrismaService 사용
### 규칙
transaction 내부 Repository 호출에는 반드시 tx 전달
---
## 2. API Response Field Rename
### 발생
리팩토링 중 customerName → name으로 변경
### 규칙
명시적 요구가 없는 API contract 변경 금지
---
## 3. 개인정보 로그
### 발생
debug 용도로 customer phone 출력
### 규칙
전화번호 원본 로그 출력 금지➕ 10-1. 좋은 규칙의 특징
구체적
검증 가능
왜 필요한지 설명됨코드를 잘 작성할 것같은 규칙은 아무 의미가 없습니다.
✅ 11. ADR이란 무엇인가?
- ADR은 Architecture Decision Record입니다.
- “왜 이 구조를 선택했는가?”를 짧게 남기는 문서입니다.
➕ 11-1. 예시
# ADR-002: Excel Export는 ExportJob 기반 비동기로 처리
## 상태
Accepted
## 문제
대량 상담 데이터를 HTTP 요청 안에서 Excel로 생성하면 timeout 가능성이 있음
## 결정
API는 ExportJob만 생성하고 실제 Excel 생성은 Worker에서 처리
## 이유
- API 응답 시간 분리
- 실패 상태 저장 가능
- Retry 가능
- 파일 만료 관리 가능
## 고려한 대안
HTTP 요청에서 직접 Excel 생성
## 선택하지 않은 이유
데이터 증가 시 timeout과 메모리 사용 위험
## 영향
ExportJob 테이블과 Worker 운영 필요- 나중에 AI가 “왜 그냥 동기로 안 하지?”라는 방향으로 되돌리는 것을 막을 수 있습니다.
✅ 12. ADR이 필요한 결정
Job/Worker 도입
Soft Delete 정책
Permission 모델
Audit Log 정책
Transaction Boundary
Error Response 형식
SSM 기반 Config
Webhook 처리 방식➕ 12-1. ADR이 필요 없는 것
버튼 색상
파일명 변경
작은 refactor
일반적인 bugfix- 장기간 유지해야 하는 구조적 결정만 ADR로 남기는 것이 좋습니다.
✅ 13. 컨텍스트를 전부 AI에게 보내면 안 되는 이유
- 문서가 많다고 전부 전달하면 오히려 품질이 떨어질 수 있습니다.
- 작업과 관계없는 정보가 많으면 중요한 규칙이 묻힐 수 있습니다.
전체 문서 20개
↓
모든 작업에 전달
↓
Context 과다
↓
중요 규칙 희석➕ 13-1. 더 좋은 방식
Task 분석
↓
관련 Domain 판단
↓
관련 Context만 선택
↓
AI Prompt에 주입- 핵심은 Context Retrieval입니다.
✅ 14. 작업 유형별 Context 선택
➕ 14-1. 상담 상태 변경
project-context
backend-rules
database-rules
permissions
api-contract
관련 ADR
common-mistakes➕ 14-2. 프론트 UI 수정
project-context
frontend-rules
api-contract
design/UI 규칙➕ 14-3. Webhook
backend-rules
security-rules
database-rules
webhook ADR
testing-rules➕ 14-4. 문서 수정
필요한 최소 context만- Task domain과 risk에 따라 Context Pack을 선택하는 방식이 효율적입니다.
✅ 15. Context Pack 개념
Context Pack:
특정 작업 유형에서 AI에게 자동으로 제공할 문서 묶음➕ 15-1. Backend Pack
name: backend
files:
- docs/ai/project-context.md
- docs/ai/architecture.md
- docs/ai/backend-rules.md
- docs/ai/api-contract.md➕ 15-2. Security Pack
name: security
files:
- docs/ai/security-rules.md
- docs/ai/permissions.md
- docs/ai/common-mistakes.md➕ 15-3. Database Pack
name: database
files:
- docs/ai/database-rules.md
- docs/ai/security-rules.md
- docs/ai/decisions/ADR-001-transaction-boundary.md- 매 작업마다 문서를 수동으로 골라 붙이지 않아도 됩니다.
✅ 16. Task Metadata와 Context Pack 연결
0909의 Task Metadata를 확장하면:
taskId: 142
project: togethermall
type: refactor
domain: consult
risk: HIGH
contextPacks:
- backend
- database
- security
allowedPaths:
- src/modules/consult
- src/modules/audit-log
blockedPaths:
- prisma/migrations
- deployment➕ 16-1. 내부 흐름
Task Metadata
↓
Context Pack 확인
↓
관련 문서 로드
↓
Prompt Builder
↓
Codex Prompt- Task Spec과 Context가 자동으로 연결되면 오케스트레이션 품질이 크게 좋아집니다.
✅ 17. Context 우선순위
- 모든 규칙의 중요도가 같은 것은 아닙니다.
Priority 1:
보안/금지 규칙
Priority 2:
Task 완료 조건
Priority 3:
API/DB Contract
Priority 4:
아키텍처 원칙
Priority 5:
스타일/선호➕ 17-1. 충돌 시 기준
Task 요청과 Security Rule 충돌:
Security Rule 우선
Task 요청과 기존 Architecture Rule 충돌:
사용자가 명시적으로 구조 변경을 요청했는지 확인
Style Rule과 기능 요구 충돌:
기능 요구 우선- Prompt Builder가 중요한 규칙을 위쪽에 배치하도록 할 수 있습니다.
✅ 18. Hard Rule과 Soft Rule
➕ 18-1. Hard Rule
반드시 지켜야 함
예:
Secret 하드코딩 금지
운영 DB 수정 금지
전화번호 로그 금지
blockedPaths 수정 금지➕ 18-2. Soft Rule
가능하면 지킴
예:
파일 크기를 작게 유지
기존 naming convention 선호
Use Case 분리 권장➕ 18-3. 표현
MUST:
Hard Rule
SHOULD:
Soft Rule
MAY:
선택 사항- AI에게 규칙 강도를 알려주면 불필요한 혼란이 줄어듭니다.
✅ 19. Context Manifest
version: 1
hardRules:
- docs/ai/security-rules.md
- docs/ai/api-contract.md
packs:
backend:
- docs/ai/project-context.md
- docs/ai/architecture.md
- docs/ai/backend-rules.md
database:
- docs/ai/database-rules.md
- docs/ai/decisions/ADR-001-transaction-boundary.md
permission:
- docs/ai/permissions.md
testing:
- docs/ai/testing-rules.md
common:
- docs/ai/common-mistakes.mdcontext-manifest.yml같은 파일로 관리할 수 있습니다.
✅ 20. Prompt Builder 구조
Task Spec
+
Hard Rules
+
Selected Context Packs
+
Common Mistakes
+
Relevant Files
=
Final Prompt➕ 20-1. 최종 프롬프트 순서
1. 작업 목적
2. 완료 조건
3. 절대 금지 사항
4. 작업 범위
5. 프로젝트 구조
6. 관련 과거 결정
7. 테스트 조건
8. 결과 보고 형식- 중요한 내용이 프롬프트 뒤쪽에 묻히지 않게 순서를 정하는 것이 좋습니다.
✅ 21. Final Prompt 예시
[Task]
상담 상태 변경 transaction을 정리한다.
[Completion]
- status/history/audit 같은 transaction
- 기존 API response 유지
- 기존 409 동작 유지
[MUST]
- 전화번호 원본 로그 금지
- blockedPaths 수정 금지
- 외부 API 호출 추가 금지
[Architecture]
- transaction boundary는 Use Case
- Repository는 전달받은 tx 사용
- Audit Log는 동일 tx 사용
[API Contract]
- 기존 응답 field rename/delete 금지
[Known Mistake]
과거 Repository에서 기본 PrismaService를 사용해 transaction이 깨진 사례가 있음.
반드시 전달된 tx를 사용할 것.
[Test]
- 정상 상태 변경
- rollback
- concurrent update
[Report]
변경 파일, 테스트, 미실행 테스트, 주의사항을 정리할 것.- 이미 상당히 구체적인 작업 프롬프트가 자동으로 만들어집니다.
✅ 22. Context 크기 제한
- 코드와 문서를 너무 많이 넣으면 비용과 처리 시간이 늘어납니다.
- 로컬 LLM에서는 컨텍스트 윈도우도 문제가 될 수 있습니다.
➕ 22-1. 우선순위
1. Task Spec
2. Hard Rule
3. 직접 관련 문서
4. 관련 코드
5. Common Mistakes
6. 참고 문서➕ 22-2. 필요하면 제외
오래된 Troubleshooting
관련 없는 Domain 문서
전체 README
전체 Git history- “많이 주는 것”보다 “관련 있는 것을 정확히 주는 것”이 더 좋습니다.
✅ 23. 관련 Troubleshooting 자동 검색
- 0907에서 만든 Troubleshooting 문서를 AI 작업 Context로 다시 사용할 수 있습니다.
Task:
Notification Worker retry 수정
↓
태그 검색:
notification
retry
timeout
↓
관련 Troubleshooting 발견
↓
Context 추가➕ 23-1. 예시
과거 문제:
Worker가 retry 시 동일 메시지를 중복 발송
현재 작업:
NotificationJob retry 정책 수정
→ 과거 문서를 자동 Context 후보로 제시- 기록이 실제 개발 품질 향상에 다시 사용되는 구조입니다.
✅ 24. 관련 ADR 자동 검색
Task Domain:
export
검색:
docs/ai/decisions/*export*
결과:
ADR-002-export-job.md➕ 24-1. Prompt에 추가
기존 결정:
Excel Export는 HTTP 요청 안에서 직접 생성하지 않고 ExportJob + Worker 구조를 사용한다.- AI가 기존 결정을 모르고 반대 방향으로 리팩토링하는 것을 줄일 수 있습니다.
✅ 25. 변경된 규칙의 Version 관리
- AI 규칙도 코드처럼 변경됩니다.
- Git으로 관리해야 언제 왜 바뀌었는지 알 수 있습니다.
docs/ai/security-rules.md
docs/ai/common-mistakes.md
context-manifest.yml➕ 25-1. Commit 예시
docs(ai): Repository transaction 규칙 추가➕ 25-2. 변경 이유
Task #142에서 transaction 내부 Repository가 기본 Prisma를 사용했던 문제 재발 방지- 프로젝트의 AI 지식도 실제 코드와 함께 발전하게 됩니다.
✅ 26. 오래된 Context 문제
- 문서가 오래되면 오히려 AI에게 잘못된 정보를 줄 수 있습니다.
- 지식베이스에도 최신성 관리가 필요합니다.
➕ 26-1. Frontmatter
---
status: active
lastReviewed: 2026-09-10
owner: backend
---➕ 26-2. 상태
ACTIVE
DEPRECATED
DRAFT
ARCHIVED➕ 26-3. 규칙
DEPRECATED 문서는 기본 Context에서 제외
ARCHIVED 문서는 검색만 허용
DRAFT는 자동 주입 금지- 문서의 양보다 신뢰도가 중요합니다.
✅ 27. Context Drift
- 코드와 문서가 서로 달라지는 문제를 Context Drift라고 볼 수 있습니다.
문서:
Controller에서 Prisma 사용 금지
실제 코드:
신규 Controller가 Prisma 직접 사용
→ Drift➕ 27-1. 해결
정기 Architecture Review
AI QA에서 규칙 위반 검사
문서 수정 시 관련 코드 확인
코드 리팩토링 시 문서 갱신- 문서가 실제 코드와 다르면 AI에게 더 나쁜 결과를 줄 수 있습니다.
✅ 28. QA에서 Context Rule 검증
0908 QA와 연결하면:
git diff
↓
Context Rules
↓
규칙 위반 검사➕ 28-1. 예시
Rule:
Controller에서 Prisma 직접 사용 금지
Diff:
consult.controller.ts에 PrismaService 추가
결과:
ARCHITECTURE_WARNING➕ 28-2. Hard Rule
Rule:
.env 파일 수정 금지
Diff:
.env.production 변경
결과:
BLOCK- 지식베이스가 단순 프롬프트 문서를 넘어 QA 규칙의 근거가 됩니다.
✅ 29. 규칙을 기계 검증 가능한 형태로 관리
- 모든 규칙을 자동 검사할 수는 없지만 일부는 구조화할 수 있습니다.
rules:
- id: no-env-change
level: BLOCK
paths:
- ".env*"
- id: migration-human-review
level: WARNING
paths:
- "prisma/migrations/**"
- id: permission-human-review
level: WARNING
paths:
- "src/**/permission/**"➕ 29-1. 두 종류의 규칙
문서형 Rule:
AI가 이해하기 위한 설명
기계형 Rule:
CLI/QA가 검사하기 위한 설정- 두 가지를 같이 사용하는 것이 좋습니다.
✅ 30. Context 생성 결과 기록
- AI에게 실제로 어떤 Context를 줬는지도 기록하면 나중에 디버깅하기 쉽습니다.
## AI Context
### Packs
- backend
- database
- security
### Files
- docs/ai/backend-rules.md
- docs/ai/database-rules.md
- docs/ai/security-rules.md
- docs/ai/common-mistakes.md
### ADR
- ADR-001-transaction-boundary.md- AI가 왜 그런 결과를 만들었는지 분석하는 데 도움이 됩니다.
✅ 31. Task Report와 Context 연결
0909의 Task Report에 추가:
## Context
- Backend Pack
- Database Pack
- Security Pack
- ADR-001 Transaction Boundary
## Rule Violations
- 없음➕ 31-1. 실패 시
문제:
AI가 API field를 rename
Context:
api-contract pack이 포함되지 않았음
재발 방지:
해당 Task type에 api-contract pack 자동 포함- 실패 원인을 모델 자체가 아니라 Context 설계 문제로 분석할 수도 있습니다.
✅ 32. AI Context 자동 개선 루프
AI 작업
↓
QA 실패
↓
Troubleshooting
↓
원인 분석
↓
규칙 부족?
├─ Yes → Knowledge 업데이트
└─ No → 코드 문제
↓
다음 Task에 자동 반영- 지금까지 만든 자동화들이 여기서 하나의 학습 루프가 됩니다.
✅ 33. 프로젝트별 Context와 공통 Context 분리
- 여러 프로젝트를 다룬다면 공통 규칙과 프로젝트 규칙을 구분하는 것이 좋습니다.
~/.llm-work/
rules/
common-security.md
common-git.md
project/
docs/ai/
project-context.md
backend-rules.md➕ 33-1. 공통
Secret 금지
Git 작업 안전 규칙
AI 작업 결과 검증 기준➕ 33-2. 프로젝트별
도메인 규칙
폴더 구조
DB 정책
API Contract
PermissionCode- 특정 프로젝트 규칙을 다른 프로젝트에 잘못 적용하는 것을 막을 수 있습니다.
✅ 34. 우선순위 기반 Context Merge
Global Hard Rules
↓
Project Hard Rules
↓
Task Spec
↓
Context Packs
↓
Relevant Knowledge➕ 34-1. 충돌 예시
Global:
운영 DB 자동 수정 금지
Task:
운영 DB column 직접 수정
결과:
Task 실행 금지- 상위 안전 규칙은 Task 요청보다 우선하게 설계할 수 있습니다.
✅ 35. 로컬 LLM을 활용한 Context 분류
- 강한 모델을 모든 단계에 사용할 필요는 없습니다.
- 로컬 LLM으로 문서 분류와 관련 Context 후보를 찾을 수 있습니다.
Task 입력
↓
로컬 LLM
↓
domain=consult
risk=HIGH
packs=backend,database
keywords=status,transaction,audit➕ 35-1. 이후
규칙 기반 검증
↓
Context Pack 결정
↓
Codex Prompt 생성- Context 선택 정도는 로컬 LLM으로 처리하기 좋은 작업입니다.
✅ 36. LLM 판단을 그대로 믿지 않기
- Context 선택도 AI가 틀릴 수 있습니다.
- 중요한 Pack은 Task type/risk에 따라 규칙으로 강제하는 것이 좋습니다.
➕ 36-1. 예시
risk=CRITICAL:
security pack 항상 포함
domain=database:
database pack 항상 포함
API DTO 변경:
api-contract pack 항상 포함➕ 36-2. LLM 역할
추가 추천:
LLM
필수 Pack:
Rule Engine- 안전 관련 Context는 deterministic하게 선택해야 합니다.
✅ 37. Context CLI 예시
llm-work context 142출력:
Task #142
Detected:
- domain: consult
- risk: HIGH
Required Context:
✓ project-context
✓ backend
✓ database
✓ security
✓ api-contract
Related ADR:
✓ ADR-001-transaction-boundary
Related Troubleshooting:
✓ consult-status-history-missing.md
Estimated Context:
12,400 tokens➕ 37-1. 옵션
llm-work context 142 --show
llm-work context 142 --compact
llm-work context 142 --exclude troubleshooting- 실제 Codex 작업 전에 어떤 Context가 들어가는지 확인할 수 있습니다.
✅ 38. Context Compact 모드
- 컨텍스트가 너무 크면 요약본을 사용할 수 있습니다.
원문 문서
↓
로컬 LLM 요약
↓
Compact Context➕ 38-1. 주의
Hard Rule:
요약하지 않고 원문 사용
일반 Architecture 설명:
요약 가능
오래된 Troubleshooting:
핵심 교훈만 요약- 보안/금지 규칙은 요약 과정에서 의미가 약해지면 안 됩니다.
✅ 39. Context Cache
- 매번 같은 문서를 읽고 요약하는 비용을 줄이기 위해 캐시를 둘 수 있습니다.
파일 hash
↓
변경 없음
↓
기존 요약 사용➕ 39-1. 캐시 키
file path
content hash
summary model/version➕ 39-2. 변경 시
hash 변경
↓
요약 다시 생성- local-llm-work-report 구조와도 자연스럽게 연결할 수 있습니다.
✅ 40. 현재 프로젝트 적용 우선순위
➕ 40-1. 1순위: 핵심 AI 문서 작성
project-context.md
backend-rules.md
security-rules.md
api-contract.md
common-mistakes.md완료 기준:
Codex에게 반복해서 설명하던 핵심 규칙이 문서화됨➕ 40-2. 2순위: Context Pack
backend
database
security
frontend
testing완료 기준:
Task에 필요한 문서를 묶음 단위로 선택 가능➕ 40-3. 3순위: Task Metadata 연결
domain
risk
contextPacks완료 기준:
Task별 필요한 Context가 자동 선택됨➕ 40-4. 4순위: ADR/Troubleshooting 검색
Task keyword
↓
관련 과거 결정/문제 검색완료 기준:
과거 실수와 설계 결정을 새 AI 작업에 재사용➕ 40-5. 5순위: QA Rule 연결
Knowledge Rule
↓
일부 규칙 기계 검증완료 기준:
문서 규칙이 실제 QA 경고/BLOCK으로 연결- 처음에는 문서화와 Context Pack만으로도 충분한 효과를 얻을 수 있습니다.
✅ 41. Codex에게 Context 관리 기능을 맡길 때 규칙
기존 llm-work CLI에 프로젝트 AI Context 관리 기능을 추가해줘.
목표:
Task마다 프로젝트 전체 문서를 무작정 전달하지 않고, 작업과 관련된 규칙과 과거 결정을 자동으로 골라 Codex Prompt에 넣고 싶다.
조건:
1. docs/ai 폴더 아래 project-context.md, architecture.md, backend-rules.md, frontend-rules.md, database-rules.md, security-rules.md, testing-rules.md, api-contract.md, permissions.md, common-mistakes.md를 관리할 수 있게 해줘
2. context-manifest.yml에서 Context Pack을 정의하게 해줘
3. backend, frontend, database, security, permission, testing Pack을 지원해줘
4. Task Metadata의 domain, risk, contextPacks를 기준으로 필요한 Pack을 선택하게 해줘
5. CRITICAL risk에는 security Pack을 반드시 포함해줘
6. database domain에는 database Pack을 강제해줘
7. API DTO/Mapper 변경 Task에는 api-contract Pack을 자동 포함해줘
8. docs/ai/decisions의 ADR을 Task keyword/domain 기준으로 검색해서 관련 문서를 후보로 보여줘
9. troubleshooting Markdown에서도 관련 domain/tag/errorCode 기준으로 후보를 찾을 수 있게 해줘
10. AI가 추천하는 Context와 Rule Engine이 강제로 넣는 Context를 구분해줘
11. Hard Rule은 요약하지 않고 원문 그대로 포함하게 해줘
12. 일반 설명 문서는 context가 너무 크면 compact summary를 사용할 수 있게 해줘
13. compact summary는 파일 hash 기반으로 cache하게 해줘
14. DEPRECATED/ARCHIVED 문서는 기본 Context에서 제외해줘
15. llm-work context <task-id> 명령으로 실제 사용될 Context Pack, 파일, ADR, Troubleshooting, 예상 크기를 보여줘
16. llm-work run에서 생성된 최종 Prompt에 선택된 Context를 자동으로 합쳐줘
17. 실제로 어떤 Context가 사용됐는지 Task Report에 기록해줘
18. Secret, 고객 개인정보, 운영 DB 값은 Context로 포함하지 않도록 sanitize 해줘
19. Context 선택 오류가 QA 실패 원인으로 확인되면 common-mistakes 또는 manifest 개선으로 이어질 수 있게 구조를 만들어줘
20. 테스트와 사용 방법을 문서화해줘➕ 41-1. 리뷰 기준
모든 문서를 무조건 Prompt에 넣지 않는가?
Task와 관련 있는 Context만 선택하는가?
보안 Pack을 deterministic하게 적용하는가?
Hard Rule이 요약으로 약해지지 않는가?
오래된 문서를 자동 제외하는가?
관련 ADR/Troubleshooting을 재사용하는가?
실제로 사용한 Context가 기록되는가?
Context에 개인정보/Secret이 들어가지 않는가?✅ 42. 실무 체크리스트
➕ 42-1. Knowledge Base
- 프로젝트 개요가 문서화되어 있는가?
- 백엔드 구조 규칙이 있는가?
- DB 규칙이 있는가?
- API Contract가 정리되어 있는가?
- Permission 정책이 있는가?
- Security Rule이 있는가?
- 테스트 기준이 있는가?
- AI의 반복 실수가 기록되어 있는가?
➕ 42-2. Context Selection
- Task domain을 판단하는가?
- Task risk를 판단하는가?
- 필요한 Pack만 포함하는가?
- Hard Rule을 항상 포함하는가?
- 관련 ADR을 찾는가?
- 관련 Troubleshooting을 찾는가?
- Deprecated 문서를 제외하는가?
- Context가 지나치게 크지 않은가?
➕ 42-3. 정확성
- 문서가 실제 코드와 일치하는가?
- 마지막 검토 날짜가 있는가?
- 과거 정책이 남아 있지 않은가?
- 설계 변경 시 ADR이 추가됐는가?
- 반복되는 AI 실수가 common-mistakes에 추가됐는가?
- Context 선택 실패 사례를 기록하는가?
- API 변경 시 api-contract가 갱신되는가?
- Permission 변경 시 권한 문서가 갱신되는가?
➕ 42-4. 보안
- 실제 Secret이 문서에 없는가?
- 운영 endpoint credential이 없는가?
- 고객 개인정보가 없는가?
- 실제 고객 사례를 넣어야 한다면 익명화했는가?
- Troubleshooting에서 민감정보가 sanitize 되었는가?
- AI Prompt 생성 전에 다시 sanitize하는가?
- Hard Rule로 운영 DB 접근을 금지하는가?
- Context 기록에도 Secret이 저장되지 않는가?
✅ 43. AI에게 프로젝트 컨텍스트 관리 체계를 물어볼 때 좋은 질문법
1인 개발 환경에서 Codex가 프로젝트 맥락을 더 정확하게 이해하도록 AI용 프로젝트 Knowledge Base와 Context Retrieval 시스템을 만들려고 해.
환경:
1. NestJS + React + Prisma + PostgreSQL 기반 온라인 휴대폰 판매몰을 운영하고 있음
2. Task Spec → Codex → QA → Human Review → Task Report 자동화가 있음
3. Codex가 반복적으로 프로젝트 규칙을 놓치는 것을 줄이고 싶음
4. docs/ai 아래에 Project Context, Architecture, Backend, Frontend, Database, Security, Testing, API Contract, Permission, Common Mistakes 문서를 관리하고 싶음
5. Architecture Decision은 ADR로 따로 기록하고 싶음
6. 과거 Troubleshooting도 새로운 작업의 Context로 재사용하고 싶음
7. 모든 문서를 매번 넣지 않고 Task domain/risk에 따라 필요한 Context Pack만 선택하고 싶음
8. Security와 DB 같은 중요한 규칙은 AI 판단이 아니라 deterministic rule로 강제하고 싶음
9. 오래되거나 deprecated된 문서는 자동 Context에서 제외하고 싶음
10. Context가 너무 크면 일반 문서는 요약하되 Hard Rule은 원문을 유지하고 싶음
11. 실제 어떤 Context를 사용했는지 Task Report에 기록하고 싶음
12. Secret, 운영 DB 정보, 고객 개인정보는 Knowledge/Prompt에 포함되면 안 됨
요청:
- docs/ai 폴더 구조
- Context Pack 설계
- context-manifest schema
- Hard/Soft Rule 구분
- Task Metadata와 Context 연결 방식
- ADR 작성 기준
- Troubleshooting 검색/재사용 방식
- Context 우선순위
- context compact/cache 구조
- stale/deprecated 문서 관리
- QA와 Knowledge Rule 연결 방식
- Prompt Builder 구조
- CLI 명령어
- 구현 우선순위
- 보안 체크리스트
를 실무적으로 정리해줘.➕ 43-1. AI 답변 검증 기준
문서를 많이 만드는 것 자체를 목표로 하지 않는가?
작업과 관련된 Context만 선택하도록 하는가?
Hard Rule과 일반 설명을 구분하는가?
보안/DB 규칙을 AI 판단에만 맡기지 않는가?
ADR을 구조적 결정 기록으로 활용하는가?
Troubleshooting을 새로운 작업에 재사용하는가?
오래된 문서 문제를 다루는가?
실제 사용 Context를 추적 가능하게 하는가?
Context와 QA를 연결하는가?📌 요약
- AI/Codex의 작업 품질은 모델 성능뿐 아니라 프로젝트 컨텍스트 품질에 크게 영향을 받습니다.
- 프로젝트 지식베이스는 개발자가 암묵적으로 알고 있는 아키텍처, DB, 권한, 보안, 테스트, API 계약을 AI도 이해할 수 있도록 명시적으로 정리한 자료입니다.
docs/ai아래에project-context,architecture,backend-rules,database-rules,security-rules,api-contract,permissions,testing-rules,common-mistakes등을 관리하면 좋습니다.- 장기간 유지해야 하는 구조적 결정은 ADR로 남겨 “무엇을 선택했는가”뿐 아니라 “왜 선택했는가”까지 기록해야 합니다.
- 모든 문서를 매 작업마다 전달하면 Context가 지나치게 커질 수 있으므로 Task의 domain과 risk에 따라 필요한 Context Pack만 선택하는 구조가 효율적입니다.
- Security, Database, API Contract처럼 중요한 Context는 AI가 선택하게 두기보다 Rule Engine으로 강제하는 것이 안전합니다.
- Hard Rule은 반드시 지켜야 하는 금지/보안 규칙이고, Soft Rule은 가능하면 따르는 아키텍처/스타일 기준으로 구분할 수 있습니다.
- 0909의 Task Metadata에
contextPacks를 추가하면 Task 정의 → Context 선택 → Prompt 생성까지 자동 연결할 수 있습니다. - 과거 ADR과 Troubleshooting 문서를 현재 Task의 domain, tag, errorCode로 검색해 다시 Context로 활용하면 작업 기록이 실제 AI 개발 품질 향상으로 이어집니다.
- 문서가 오래되어 실제 코드와 달라지는 Context Drift도 관리해야 하며
ACTIVE,DEPRECATED,ARCHIVED같은 상태와 마지막 검토 시점을 두는 것이 좋습니다. - 일부 지식 규칙은 QA에서도 기계적으로 검사할 수 있으며, 예를 들어
.env변경은 BLOCK, migration/Auth/Permission 변경은 강한 WARNING으로 연결할 수 있습니다. - AI 작업 실패가 반복되면 Troubleshooting → Common Mistakes → Knowledge Rule → 다음 Prompt 자동 주입으로 이어지는 개선 루프를 만들 수 있습니다.
- Context 선택에도 AI를 활용할 수 있지만, 보안이나 운영 위험과 관련된 필수 규칙은 deterministic하게 적용해야 합니다.
- 현재 단계에서는 핵심 AI 문서 작성 → Context Pack → Task Metadata 연결 → ADR/Troubleshooting 검색 → QA Rule 연동 순서로 적용하는 것이 현실적입니다.
