agentic-development-principles
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese에이전틱 개발 원칙 (Agentic Development Principles)
智能体开发原则（Agentic Development Principles）
"AI는 부조종사, 주인공은 당신입니다" AI 에이전트는 개발자의 생각을 증폭시키고 반복 작업을 대신하지만, 최종 결정권과 책임은 항상 개발자에게 있습니다.
"AI是副驾驶，你才是主角" AI Agent是为了放大开发者的思路并替代重复工作，但最终的决策权和责任始终在开发者手中。
When to use this skill
何时使用此方法
- AI 에이전트와 협업 세션 시작 시
- 복잡한 작업 시작 전 접근 방식 결정
- 컨텍스트 관리 전략 수립
- 생산성 향상을 위한 워크플로우 점검
- 팀원에게 AI 협업 사용법 온보딩
- 새로운 AI 도구 도입 시 기본 원칙 적용
- 开启与AI Agent的协作会话时
- 开始复杂任务前确定工作方法
- 制定上下文管理策略
- 检查工作流程以提升生产力
- 向团队成员传授AI协作方法
- 引入新AI工具时应用基础原则
원칙 1: 분해하고 정복하라 (Divide and Conquer)
原则1：分而治之（Divide and Conquer）
핵심 개념
核心概念
AI는 크고 모호한 작업보다 작고 명확한 지시에 훨씬 더 좋은 성능을 발휘합니다.
AI在处理小而明确的指令时，性能远优于处理大而模糊的任务。
적용 방법
应用方法
| 잘못된 예 | 올바른 예 |
|---|---|
| "로그인 페이지 만들어줘" | 1. "로그인 폼 UI 컴포넌트 생성" |
| 2. "로그인 API 엔드포인트 작성" | |
| 3. "인증 로직 연결" | |
| 4. "테스트 코드 작성" | |
| "앱 최적화해줘" | 1. "성능 병목 지점 분석" |
| 2. "데이터베이스 쿼리 최적화" | |
| 3. "프론트엔드 번들 크기 줄이기" |
| 错误示例 | 正确示例 |
|---|---|
| "帮我做一个登录页面" | 1. "创建登录表单UI组件" |
| 2. "编写登录API端点" | |
| 3. "连接认证逻辑" | |
| 4. "编写测试代码" | |
| "帮我优化这个应用" | 1. "分析性能瓶颈" |
| 2. "优化数据库查询" | |
| 3. "减小前端打包体积" |
실전 패턴: 단계적 구현
实战模式：分步实现
1단계: 모델/스키마 설계 및 검증
2단계: 핵심 로직 구현 (최소 기능)
3단계: API/인터페이스 연결
4단계: 테스트 작성 및 실행
5단계: 통합 및 리팩토링1阶段：模型/架构设计与验证
2阶段：核心逻辑实现（最小功能）
3阶段：API/接口连接
4阶段：编写并执行测试
5阶段：集成与重构검증 포인트
验证要点
- 각 단계가 독립적으로 검증 가능한가?
- 실패 시 해당 단계만 수정하면 되는가?
- AI가 명확히 이해할 수 있는 범위인가?
- 每个阶段是否可独立验证？
- 失败时是否只需修改对应阶段？
- 是否在AI能清晰理解的范围内？
원칙 2: 컨텍스트는 우유와 같다 (Context is like Milk)
原则2：上下文如同牛奶（Context is like Milk）
핵심 개념
核心概念
컨텍스트(AI의 작업 기억)는 항상 신선하고 압축된 상태로 유지해야 합니다.
- 오래되고 관련 없는 정보는 AI 성능을 저하시킴
- 컨텍스트 드리프트: 여러 주제 혼합 시 성능 최대 39% 저하 (연구 결과)
上下文（AI的工作记忆）必须始终保持新鲜且精简的状态。
- 过时且无关的信息会降低AI性能
- 上下文漂移：混合多个主题时，性能最多下降39%（研究结果）
컨텍스트 관리 전략
上下文管理策略
전략 1: 단일 목적 대화
策略1：单一目标会话
세션 1: 인증 시스템 작업
세션 2: UI 컴포넌트 작업
세션 3: 테스트 코드 작성
세션 4: DevOps/배포 작업- 한 대화에서 여러 주제를 섞지 않기
- 새로운 주제는 새 세션에서 시작
会话1：处理认证系统
会话2：处理UI组件
会话3：编写测试代码
会话4：DevOps/部署工作- 同一会话中不混合多个主题
- 新主题从新会话开始
전략 2: HANDOFF.md 기법
策略2：HANDOFF.md技巧
대화가 길어질 때 핵심만 요약하여 새 세션에 전달:
markdown
undefined当会话过长时，仅总结核心内容并传递到新会话：
markdown
undefinedHANDOFF.md
HANDOFF.md
완료된 작업
已完成工作
- ✅ 사용자 인증 API 구현 완료
- ✅ JWT 토큰 발급 로직 작성
- ✅ 实现用户认证API
- ✅ 编写JWT令牌发放逻辑
현재 상태
当前状态
- 토큰 갱신 로직 작업 중
- 正在处理令牌刷新逻辑
다음 작업
下一步工作
- 리프레시 토큰 구현
- 로그아웃 엔드포인트 추가
- 实现刷新令牌
- 添加登出端点
시도했지만 실패한 것
尝试过但失败的操作
- Redis 세션 저장소 연동 실패 (네트워크 이슈)
- Redis会话存储集成失败（网络问题）
주의사항
注意事项
- 기존 세션 관리 코드와 충돌 주의
undefined- 注意与现有会话管理代码冲突
undefined전략 3: 컨텍스트 상태 모니터링
策略3：上下文状态监控
- 대화가 길어지면 AI에게 현재 상태 요약 요청
- 필요시 대화 초기화 후 HANDOFF.md로 재시작
- 会话过长时，请求AI总结当前状态
- 必要时重置会话，通过HANDOFF.md重新开始
전략 4: 최적화 지표
策略4：优化指标
| 지표 | 권장 값 | 조치 |
|---|---|---|
| 대화 길이 | 적정 수준 유지 | 길어지면 HANDOFF.md 생성 |
| 주제 수 | 1개 (단일 목적) | 새 주제는 새 세션 |
| 활성 파일 | 필요한 것만 | 불필요한 컨텍스트 제거 |
| 指标 | 推荐值 | 操作 |
|---|---|---|
| 会话长度 | 保持合理水平 | 过长时生成HANDOFF.md |
| 主题数量 | 1个（单一目标） | 新主题开启新会话 |
| 活跃文件 | 仅保留必要文件 | 移除不必要的上下文 |
원칙 3: 올바른 추상화 수준 선택
原则3：选择合适的抽象层级
핵심 개념
核心概念
상황에 따라 적절한 추상화 수준을 선택합니다.
| 모드 | 설명 | 사용 시점 |
|---|---|---|
| Vibe Coding | 전체 구조만 보는 높은 수준 | 빠른 프로토타이핑, 아이디어 검증, 일회성 프로젝트 |
| Deep Dive | 코드 한 줄씩 파고드는 낮은 수준 | 버그 수정, 보안 검토, 성능 최적화, 프로덕션 코드 |
根据场景选择合适的抽象层级。
| 模式 | 说明 | 使用时机 |
|---|---|---|
| Vibe Coding | 只看整体结构的高层级 | 快速原型开发、想法验证、一次性项目 |
| Deep Dive | 逐行钻研代码的低层级 | 修复Bug、安全审查、性能优化、生产代码开发 |
실전 적용
实战应用
새 기능 추가 시:
1. 높은 추상화: "사용자 프로필 페이지를 만들어줘" → 전체 구조 파악
2. 중간 추상화: "프로필 편집 폼의 유효성 검사 로직을 보여줘" → 특정 기능 검토
3. 낮은 추상화: "이 정규식이 왜 이메일 유효성 검사에 실패하는지 설명해줘" → 세부 디버깅添加新功能时：
1. 高层级抽象："帮我做一个用户资料页面" → 掌握整体结构
2. 中层级抽象："展示资料编辑表单的验证逻辑" → 审查特定功能
3. 低层级抽象："解释为什么这个正则表达式无法通过邮箱验证" → 细节调试추상화 수준 선택 가이드
抽象层级选择指南
- 프로토타입/PoC: Vibe Coding 80%, Deep Dive 20%
- 프로덕션 코드: Vibe Coding 30%, Deep Dive 70%
- 버그 수정: Deep Dive 100%
- 原型/PoC：Vibe Coding占80%，Deep Dive占20%
- 生产代码：Vibe Coding占30%，Deep Dive占70%
- Bug修复：Deep Dive占100%
원칙 4: 자동화의 자동화 (Automation of Automation)
原则4：自动化的自动化（Automation of Automation）
핵심 개념
核心概念
같은 작업을 3번 이상 반복했다면 → 자동화 방법을 찾아라
그 자동화 과정 자체도 → 자동화하라如果同一工作重复3次以上 → 寻找自动化方法
连自动化的过程本身 → 也要自动化자동화 레벨 진화
自动化层级演进
| Level | 방식 | 예시 |
|---|---|---|
| 1 | 수동 복사/붙여넣기 | AI 출력 → 터미널에 복사 |
| 2 | 터미널 통합 | AI 도구 직접 사용 |
| 3 | 음성 입력 | 음성 전사 시스템 |
| 4 | 반복 지시 자동화 | 프로젝트 설정 파일 활용 |
| 5 | 워크플로우 자동화 | 커스텀 명령어/스크립트 |
| 6 | 판단 자동화 | Skills 활용 |
| 7 | 규칙 강제 자동화 | Hooks/가드레일 활용 |
| 层级 | 方式 | 示例 |
|---|---|---|
| 1 | 手动复制/粘贴 | 将AI输出复制到终端 |
| 2 | 终端集成 | 直接使用AI工具 |
| 3 | 语音输入 | 语音转写系统 |
| 4 | 重复指令自动化 | 利用项目配置文件 |
| 5 | 工作流自动化 | 自定义命令/脚本 |
| 6 | 判断自动化 | 利用Skills |
| 7 | 规则强制自动化 | 利用Hooks/防护机制 |
자동화 대상 식별 체크리스트
自动化目标识别清单
- 같은 명령어를 3번 이상 실행하는가?
- 같은 설명을 반복하는가?
- 같은 패턴의 코드를 자주 작성하는가?
- 같은 검증 절차를 반복하는가?
- 是否重复执行同一命令3次以上？
- 是否重复同一说明？
- 是否经常编写同一模式的代码？
- 是否重复同一验证流程？
자동화 우선순위
自动化优先级
- 높음: 매일 반복하는 작업
- 중간: 주 1회 이상 반복하는 작업
- 낮음: 월 1회 정도의 작업
- 高：每天重复的工作
- 中：每周重复1次以上的工作
- 低：每月重复1次左右的工作
원칙 5: 신중함과 속도의 균형 (Plan vs Execute)
原则5：谨慎与速度的平衡（Plan vs Execute）
계획 모드 (Plan Mode)
规划模式（Plan Mode）
분석만 하고 실행하지 않음 - 검토 후 승인
사용 시점:
- 처음 해보는 복잡한 작업
- 여러 파일에 걸친 대규모 리팩토링
- 아키텍처 변경
- 데이터베이스 마이그레이션
- 되돌리기 어려운 작업
仅分析不执行 - 审核后再批准
使用时机:
- 首次尝试的复杂工作
- 跨多个文件的大规模重构
- 架构变更
- 数据库迁移
- 难以回滚的工作
실행 모드 (Execute Mode)
执行模式（Execute Mode）
AI가 직접 코드 수정 및 명령 실행
사용 시점:
- 간단하고 명확한 작업
- 충분히 검증된 패턴의 작업
- 샌드박스/컨테이너 환경
- 되돌리기 쉬운 작업
AI直接修改代码并执行命令
使用时机:
- 简单明确的工作
- 已充分验证的模式化工作
- 沙箱/容器环境
- 容易回滚的工作
권장 비율
推荐比例
- 계획 모드: 70-90% (기본값으로 사용)
- 실행 모드: 10-30% (안전한 환경에서만)
- 规划模式：70-90%（默认使用）
- 执行模式：10-30%（仅在安全环境中使用）
안전 원칙
安全原则
- ⚠️ 위험한 명령어 자동 실행은 격리된 환경에서만
- 중요 데이터 변경 전 반드시 백업
- 되돌릴 수 없는 작업은 항상 계획 모드
- ⚠️ 危险命令的自动执行仅在隔离环境中进行
- 修改重要数据前务必备份
- 无法回滚的工作始终使用规划模式
원칙 6: 검증과 회고 (Verify and Reflect)
原则6：验证与复盘（Verify and Reflect）
출력 검증 방법
输出验证方法
-
테스트 코드 작성
"이 함수에 대한 테스트를 작성해줘. 엣지 케이스도 포함해야 해." -
시각적 검토
- 변경된 파일들을 diff로 확인
- 원하지 않는 변경 사항 되돌리기
-
Draft PR / 코드 리뷰
"이 변경사항으로 draft PR을 만들어줘" -
자기 검증 요청
"방금 생성한 코드를 다시 검토해줘. 모든 주장을 검증하고, 끝에 검증 결과를 표로 정리해줘."
-
编写测试代码
"帮我编写这个函数的测试，要包含边缘案例。" -
视觉审查
- 通过diff查看修改的文件
- 回滚不需要的变更
-
Draft PR / 代码审查
"帮我用这些变更创建一个Draft PR" -
请求自我验证
"帮我重新检查刚才生成的代码。 验证所有内容，并在最后用表格整理验证结果。"
검증 체크리스트
验证清单
- 코드가 의도한 대로 동작하는가?
- 엣지 케이스가 처리되었는가?
- 보안 취약점은 없는가?
- 테스트가 충분한가?
- 성능에 문제가 없는가?
- 代码是否按预期运行？
- 是否处理了边缘案例？
- 是否存在安全漏洞？
- 测试是否充分？
- 性能是否有问题？
회고 질문
复盘问题
- 이 세션에서 무엇을 배웠는가?
- 다음에 더 잘할 수 있는 것은?
- 자동화할 수 있는 반복 작업이 있었는가?
- 本次会话学到了什么？
- 下次如何做得更好？
- 有没有可以自动化的重复工作？
Quick Reference
快速参考
6대 원칙 요약
6大原则总结
| 원칙 | 핵심 | 실천 |
|---|---|---|
| 1. 분해정복 | 작고 명확한 단위 | 독립 검증 가능한 단계로 분할 |
| 2. 컨텍스트 관리 | 신선하게 유지 | 단일 목적 대화, HANDOFF.md |
| 3. 추상화 선택 | 상황별 깊이 | Vibe ↔ Deep Dive 조절 |
| 4. 자동화² | 반복 제거 | 3회 반복 시 자동화 |
| 5. 계획/실행 균형 | 신중함 우선 | 계획 70-90%, 실행 10-30% |
| 6. 검증 회고 | 출력 확인 | 테스트, 리뷰, 자기 검증 |
| 原则 | 核心 | 实践 |
|---|---|---|
| 1. 分而治之 | 小而明确的单元 | 拆分为可独立验证的步骤 |
| 2. 上下文管理 | 保持新鲜 | 单一目标会话、HANDOFF.md |
| 3. 抽象层级选择 | 适配场景的深度 | 调整Vibe ↔ Deep Dive模式 |
| 4. 自动化的自动化 | 消除重复 | 重复3次则自动化 |
| 5. 规划/执行平衡 | 优先谨慎 | 规划70-90%，执行10-30% |
| 6. 验证与复盘 | 确认输出 | 测试、审查、自我验证 |
마스터리 규칙
精通规则
"AI 도구를 진정으로 마스터하려면 충분히 많이 사용해봐야 한다"
사용을 통한 학습이 핵심 - 이론만으로는 부족하고, 실제 프로젝트에서 다양한 상황을 경험해야 합니다.
"要真正掌握AI工具，必须充分使用它"
通过使用学习是核心 - 仅靠理论不够，需要在实际项目中经历各种场景。
황금률
黄金法则
AI에게 지시할 때:
1. 명확하게 (Specific)
2. 단계별로 (Step-by-step)
3. 검증 가능하게 (Verifiable)向AI下达指令时：
1. 明确具体（Specific）
2. 分步执行（Step-by-step）
3. 可验证（Verifiable）Best Practices
最佳实践
DO (권장)
DO（推荐）
- 하나의 대화에서는 하나의 명확한 목표에 집중
- 컨텍스트를 주기적으로 정리
- 복잡한 작업 전 계획 수립
- 출력 결과 항상 검증
- 반복 작업은 자동화
- 同一会话专注于一个明确目标
- 定期整理上下文
- 复杂工作前制定规划
- 始终验证输出结果
- 自动化重复工作
DON'T (금지)
DON'T（禁止）
- 여러 관련 없는 작업을 한 대화에서 처리
- 컨텍스트가 가득 찬 상태로 계속 작업
- 위험한 명령어 무분별하게 자동 실행
- AI 출력을 검증 없이 그대로 사용
- 같은 작업을 반복하면서 자동화하지 않기
- 同一会话处理多个无关工作
- 上下文已满时继续工作
- 随意自动执行危险命令
- 直接使用AI输出而不验证
- 重复同一工作却不自动化