Back to Details

agentic-principles

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AI 에이전트 협업 핵심 원칙 (Agentic Development Principles)

AI Agent协作核心原则（Agentic Development Principles）

"AI는 부조종사, 주인공은 당신입니다" AI 에이전트는 개발자의 생각을 증폭시키고 반복 작업을 대신하지만, 최종 결정권과 책임은 항상 개발자에게 있습니다.
"AI是副驾驶，你才是主角" AI Agent是为了放大开发者的思路、替代重复工作，但最终的决策权和责任始终在开发者手中。

When to use this skill

何时使用此Skill

  • AI 에이전트 세션 시작 시 기본 원칙 확인
  • 복잡한 작업 시작 전 접근 방식 결정
  • 컨텍스트 관리 전략 수립
  • 생산성 향상을 위한 워크플로우 점검
  • 팀원에게 AI 에이전트 사용법 온보딩
  • 启动AI Agent会话前确认基本原则
  • 复杂任务开始前确定工作方法
  • 制定上下文管理策略
  • 为提升生产力检查工作流程
  • 向团队成员培训AI Agent的使用方法

원칙 1: 분해하고 정복하라 (Divide and Conquer)

原则1：分而治之（Divide and Conquer）

핵심 개념

核心概念

AI는 크고 모호한 작업보다 작고 명확한 지시에 훨씬 더 좋은 성능을 발휘합니다.
AI在处理小而明确的指令时，表现远优于大而模糊的任务。

적용 방법

应用方法

잘못된 예올바른 예
"로그인 페이지 만들어줘"1. "로그인 폼 UI 컴포넌트 생성"
2. "로그인 API 엔드포인트 작성"
3. "인증 로직 연결"
4. "테스트 코드 작성"
错误示例正确示例
"帮我做个登录页面"1. "创建登录表单UI组件"
2. "编写登录API端点"
3. "连接认证逻辑"
4. "编写测试代码"

실전 패턴: 단계적 구현

实战模式：分步实现

1단계: 모델/스키마 설계 및 검증
2단계: 핵심 로직 구현 (최소 기능)
3단계: API/인터페이스 연결
4단계: 테스트 작성 및 실행
5단계: 통합 및 리팩토링
1阶段：模型/ schema设计及验证
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
undefined

HANDOFF.md

HANDOFF.md

완료된 작업

已完成工作

  • 사용자 인증 API 구현 완료
  • JWT 토큰 발급 로직 작성
  • 完成用户认证API实现
  • 编写JWT令牌颁发逻辑

현재 상태

当前状态

  • 토큰 갱신 로직 작업 중
  • 正在开发令牌刷新逻辑

다음 작업

下一步工作

  • 리프레시 토큰 구현
  • 로그아웃 엔드포인트 추가
  • 实现刷新令牌
  • 添加登出端点

주의사항

注意事项

  • 기존 세션 관리 코드와 충돌 주의
undefined
  • 注意与现有会话管理代码冲突
undefined

전략 3: 컨텍스트 상태 확인

策略3：检查上下文状态

  • Claude: 
    /context
    , 
    /clear
  • Gemini: 새 세션 시작
  • ChatGPT: 새 채팅 시작
  • Claude: 
    /context
    , 
    /clear
  • Gemini: 开启新会话
  • ChatGPT: 开启新聊天

최적화 지표

优化指标

  • 활성 도구/플러그인: 최소화 유지
  • 대화 길이: 너무 길어지면 HANDOFF.md 생성 후 새 세션
  • 活跃工具/插件：保持最小化
  • 对话长度：过长时生成HANDOFF.md后开启新会话

원칙 3: 올바른 추상화 수준 선택

原则3：选择合适的抽象层级

핵심 개념

核心概念

상황에 따라 적절한 추상화 수준을 선택합니다.
모드설명사용 시점
Vibe Coding전체 구조만 보는 높은 수준빠른 프로토타이핑, 아이디어 검증, 일회성 프로젝트
Deep Dive코드 한 줄씩 파고드는 낮은 수준버그 수정, 보안 검토, 성능 최적화, 프로덕션 코드
根据场景选择合适的抽象层级。
模式说明使用场景
Vibe Coding只看整体结构的高层级快速原型开发、创意验证、一次性项目
Deep Dive逐行钻研代码的低层级修复Bug、安全审查、性能优化、生产环境代码

실전 적용

实战应用

새 기능 추가 시:
1. 높은 추상화: "사용자 프로필 페이지를 만들어줘" → 전체 구조 파악
2. 중간 추상화: "프로필 편집 폼의 유효성 검사 로직을 보여줘" → 특정 기능 검토
3. 낮은 추상화: "이 정규식이 왜 이메일 유효성 검사에 실패하는지 설명해줘" → 세부 디버깅
添加新功能时：
1. 高层级抽象："帮我做个用户资料页面" → 掌握整体结构
2. 中层级抽象："展示资料编辑表单的验证逻辑" → 审查特定功能
3. 低层级抽象："解释为什么这个正则表达式在邮箱验证中失败" → 细节调试

원칙 4: 자동화의 자동화 (Automation of Automation)

原则4：自动化的自动化（Automation of Automation）

핵심 개념

核心概念

같은 작업을 3번 이상 반복했다면 → 자동화 방법을 찾아라
그 자동화 과정 자체도 → 자동화하라
如果同一任务重复3次以上 → 寻找自动化方法
连这个自动化过程本身 → 也要自动化

자동화 레벨 진화

自动化层级进化

Level방식예시
1수동 복사/붙여넣기ChatGPT → 터미널
2터미널 통합Claude Code, Gemini CLI 직접 사용
3음성 입력음성 전사 시스템
4반복 지시 자동화프로젝트 설명 파일 활용
5워크플로우 자동화커스텀 명령어/스킬
6판단 자동화AI Skills 활용
7규칙 강제 자동화Hooks/Guard Rails
层级方式示例
1手动复制/粘贴ChatGPT → 终端
2终端集成直接使用Claude Code、Gemini CLI
3语音输入语音转写系统
4重复指令自动化利用项目说明文件
5工作流自动化自定义命令/Skill
6判断自动化利用AI Skills
7规则强制自动化Hooks/Guard Rails

자동화 대상 식별

自动化对象识别

  • 같은 명령어를 3번 이상 실행하는가?
  • 같은 설명을 반복하는가?
  • 같은 패턴의 코드를 자주 작성하는가?
  • 是否重复执行同一命令3次以上？
  • 是否重复同一说明？
  • 是否经常编写同一模式的代码？

원칙 5: 계획 모드 vs 실행 모드

原则5：计划模式 vs 执行模式

계획 모드 (Plan First)

计划模式（Plan First）

분석만 하고 수정하지 않음
사용 시점:
  • 처음 해보는 복잡한 작업
  • 여러 파일에 걸친 대규모 리팩토링
  • 아키텍처 변경
  • 데이터베이스 마이그레이션
仅分析不修改
使用场景：
  • 首次接触的复杂任务
  • 跨多个文件的大规模重构
  • 架构变更
  • 数据库迁移

실행 모드 (Just Do It)

执行模式（Just Do It）

사용 시점:
  • 간단하고 명확한 작업
  • 실험적인 프로토타입
  • 반복적이고 시간이 많이 걸리는 작업
  • 반드시 안전한 환경(컨테이너 등)에서 사용
使用场景：
  • 简单明确的任务
  • 实验性原型
  • 重复性、耗时的任务
  • 必须在安全环境（如容器）中使用

권장 비율

推荐比例

  • 계획 모드: 90% (기본값으로 사용)
  • 실행 모드: 10% (안전한 환경에서만)
  • 计划模式：90%（默认使用）
  • 执行模式：10%（仅在安全环境中使用）

원칙 6: 검증과 회고

原则6：验证与复盘

출력 검증 방법

输出验证方法

  1. 테스트 코드 작성
    "이 함수에 대한 테스트를 작성해줘. 엣지 케이스도 포함해야 해."
  2. 시각적 검토
    • 변경된 파일들을 diff로 확인
    • 원하지 않는 변경 사항 되돌리기
  3. Draft PR 생성
    "draft PR을 만들어줘"
  4. 자기 검증 요청
    "방금 생성한 코드를 다시 검토해줘.
모든 주장을 검증하고, 끝에 검증 결과를 표로 정리해줘."
  1. 编写测试代码
    "帮我编写这个函数的测试，要包含边缘案例。"
  2. 视觉审查
    • 通过diff查看修改的文件
    • 回滚不需要的修改
  3. 创建Draft PR
    "帮我创建Draft PR"
  4. 请求自我验证
    "帮我重新检查刚才生成的代码。
验证所有内容，并在最后用表格整理验证结果。"

검증 체크리스트

验证检查表

  • 코드가 의도한 대로 동작하는가?
  • 엣지 케이스가 처리되었는가?
  • 보안 취약점은 없는가?
  • 테스트가 충분한가?
  • 代码是否按预期运行？
  • 是否处理了边缘案例？
  • 是否存在安全漏洞？
  • 测试是否充分？

Multi-Agent 워크플로우 적용

多Agent工作流应用

에이전트별 역할 분담

各Agent角色分工

AgentRoleBest For
ClaudeOrchestrator계획 수립, 코드 생성, 스킬 해석
GeminiAnalyst대용량 분석 (1M+ 토큰), 리서치
CodexExecutor명령 실행, 빌드, 배포
Agent角色适用场景
Claude编排者制定计划、生成代码、解析Skill
Gemini分析师大容量分析（1M+令牌）、调研
Codex执行者执行命令、构建、部署

오케스트레이션 패턴

编排模式

[계획 에이전트] 계획 수립 → [분석 에이전트] 분석/리서치 → [실행 에이전트] 코드 작성 → [검증] 테스트 → [종합] 결과 정리
[计划Agent] 制定计划 → [分析Agent] 分析/调研 → [执行Agent] 编写代码 → [验证] 测试 → [汇总] 整理结果

Quick Reference

快速参考

6대 원칙 요약

6大原则总结

1. 분해정복    → 작고 명확한 단계로 분할
2. 컨텍스트   → 신선하게, 단일 목적 대화
3. 추상화     → Vibe ↔ Deep Dive 상황별
4. 자동화     → 3회 반복 시 자동화
5. 계획/실행  → 계획 90%, 실행 10%
6. 검증/회고  → 테스트, PR, 자기 검증
1. 分而治之    → 拆分为小而明确的步骤
2. 上下文     → 保持新鲜，单一目标对话
3. 抽象化     → 根据场景切换Vibe ↔ Deep Dive
4. 自动化     → 重复3次时自动化
5. 计划/执行  → 计划90%，执行10%
6. 验证/复盘  → 测试、PR、自我验证

핵심 질문

核心问题

- 이 작업을 더 작게 나눌 수 있는가?
- 컨텍스트가 오염되지 않았는가?
- 올바른 추상화 수준인가?
- 3번 이상 반복했는가?
- 계획을 먼저 세웠는가?
- 결과를 검증했는가?
- 这项任务还能拆得更小吗？
- 上下文是否未被污染？
- 是否选择了正确的抽象层级？
- 是否重复了3次以上？
- 是否先制定了计划？
- 是否验证了结果？

References

参考资料