From 131733ba4d77a9b2ac19d7679a5da9729922d7ad Mon Sep 17 00:00:00 2001 From: junwoojeong100 Date: Fri, 12 Jun 2026 08:42:16 +0900 Subject: [PATCH] chore: reduce token usage in .github config files Trim redundancy across instruction, prompt, agent, and skill markdown without removing any behavioral rules or API facts. - Remove duplicate mermaid diagrams from the 4 pattern coordinator agents; the numbered routing list already states the same flow - Consolidate orchestrator's thrice-stated delegation policy and compress selection heuristics into a single table - Condense the repeated AGENTS.md footer in all 7 agents to one line - Deduplicate builder/skeleton patterns in copilot-instructions and the add-agent prompt by deferring detail to the agent-framework-codegen skill - Tighten python.instructions and drop 3 SKILL.md troubleshooting rows that duplicate inline section notes Net -138 lines (~10% smaller) with all rules preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/code_generation.agent.md | 21 +------ .github/agents/debate_critic.agent.md | 22 +------ .github/agents/debugger.agent.md | 4 +- .github/agents/generator_evaluator.agent.md | 20 +------ .github/agents/orchestrator.agent.md | 59 +++++-------------- .github/agents/planner_executor.agent.md | 17 +----- .github/agents/reviewer.agent.md | 4 +- .github/copilot-instructions.md | 17 ++---- .github/instructions/python.instructions.md | 19 ++---- .github/prompts/add-agent.prompt.md | 20 +------ .../skills/agent-framework-codegen/SKILL.md | 3 - 11 files changed, 34 insertions(+), 172 deletions(-) diff --git a/.github/agents/code_generation.agent.md b/.github/agents/code_generation.agent.md index d23a7e6..4b98a25 100644 --- a/.github/agents/code_generation.agent.md +++ b/.github/agents/code_generation.agent.md @@ -18,23 +18,6 @@ You are the **Code Generation Coordinator** for this project. ### Routing: Design → Implement → Review Cycle -```mermaid -graph TD - Start[요구사항 정의] --> A[Architect: 코드 설계] - A --> D1[Developer: 코드 구현] - D1 --> R1[Reviewer: 코드 리뷰] - R1 --> P{Pass?} - P -->|Yes| F[최종 산출물] - P -->|No / Revise| D2[Developer: 피드백 반영 수정] - D2 --> R2[Reviewer: 재리뷰] - R2 --> P2{Pass?} - P2 -->|Yes| F - P2 -->|No / Revise| D3[Developer: 추가 수정] - D3 --> R3[Reviewer: 최종 리뷰] - R3 --> F - F --> Doc[Scribe: 문서화] -``` - 1. **Architect** → 코드 설계 (구조, 인터페이스, 파일 구성, 의존성, 디자인 패턴) 2. **Developer** → 설계에 따라 코드 구현 3. **Reviewer** → 코드 리뷰 (Pass/Revise 판정) @@ -74,6 +57,4 @@ Reviewer는 다음 기준으로 코드를 평가한다: | **에러 처리** | 예외 처리, 엣지 케이스 대응 | | **테스트 가능성** | 단위/통합 테스트 작성 용이성 | -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/debate_critic.agent.md b/.github/agents/debate_critic.agent.md index 711a913..cd61c00 100644 --- a/.github/agents/debate_critic.agent.md +++ b/.github/agents/debate_critic.agent.md @@ -19,24 +19,6 @@ You are the **Debate & Critic Coordinator** for this project. ### Routing: Round 기반 순차 진행 -```mermaid -graph TD - Start[주제 정의] --> R1[Round 1] - R1 --> P1[Proposer: 입장 제시] - P1 --> O1[Opponent: 반대 논증] - O1 --> C1[Critic: 양측 평가] - C1 --> S1[Synthesizer: 종합] - S1 --> D{수렴?} - D -->|No| R2[Round 2+] - D -->|Yes| F[최종 결론] - R2 --> P2[Proposer: 보완] - P2 --> O2[Opponent: 재반박] - O2 --> C2[Critic: 재평가] - C2 --> S2[Synthesizer: 재종합] - S2 --> D - F --> Doc[Scribe: 문서화] -``` - 1. **Proposer** → 입장 제시 2. **Opponent** → 반대 논증 3. **Critic** → 양측 평가 @@ -53,6 +35,4 @@ graph TD - 각 에이전트는 이전 에이전트의 출력을 참고하여 작업한다. - 사용자 요청을 받으면 즉시 어떤 에이전트를 스폰하는지 간단히 알려준 후 작업을 시작한다. -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/debugger.agent.md b/.github/agents/debugger.agent.md index 3f0f53e..3b213ca 100644 --- a/.github/agents/debugger.agent.md +++ b/.github/agents/debugger.agent.md @@ -57,6 +57,4 @@ tools: ["read", "search", "execute"] 2. ... ``` -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/generator_evaluator.agent.md b/.github/agents/generator_evaluator.agent.md index 7069c01..589d0d8 100644 --- a/.github/agents/generator_evaluator.agent.md +++ b/.github/agents/generator_evaluator.agent.md @@ -18,22 +18,6 @@ You are the **Generator & Evaluator Coordinator** for this project. ### Routing: Generate-Evaluate-Refine Cycle -```mermaid -graph TD - Start[요구사항 정의] --> G1[Generator: 초안 생성] - G1 --> E1[Evaluator: 평가·채점] - E1 --> D{Pass?} - D -->|No| R1[Refiner: 피드백 반영 개선] - D -->|Yes| F[최종 산출물] - R1 --> E2[Evaluator: 재평가] - E2 --> D2{Pass?} - D2 -->|No| R2[Refiner: 추가 개선] - D2 -->|Yes| F - R2 --> E3[Evaluator: 최종 평가] - E3 --> F - F --> Doc[Scribe: 문서화] -``` - 1. **Generator** → 초안 생성 2. **Evaluator** → 기준표 기반 평가 (Pass/Fail 판정) 3. **Pass** → Scribe가 최종 문서화 @@ -50,6 +34,4 @@ graph TD - 최대 3 Cycles. 초과 시 현재 최선 결과로 종료하고 Scribe가 기록한다. - 사용자 요청을 받으면 즉시 어떤 에이전트를 스폰하는지 간단히 알려준 후 작업을 시작한다. -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/orchestrator.agent.md b/.github/agents/orchestrator.agent.md index 2f3ddcd..d964621 100644 --- a/.github/agents/orchestrator.agent.md +++ b/.github/agents/orchestrator.agent.md @@ -8,12 +8,8 @@ appropriate collaboration pattern, and then drives that pattern's workflow to co ## Your Role -1. Analyze the user's request -2. Select the best-fit collaboration pattern -3. Delegate to a specialized pattern agent first when one exists -4. Only when no dedicated pattern agent exists, execute the workflow inline phase by phase - while still delegating sub-tasks that already have specialized agents - (예: 코드 리뷰는 `reviewer`, 환경/런타임 진단은 `debugger`) +1. Analyze the user's request and select the best-fit collaboration pattern +2. Drive that pattern to completion via delegation (see Execution Flow) ## Available Patterns @@ -29,22 +25,12 @@ appropriate collaboration pattern, and then drives that pattern's workflow to co ## Selection Heuristics -### → Planner-Executor -- "계획해줘", "구현해줘", "만들어줘", "셋업해줘", "마이그레이션", "리팩토링" -- Keywords: plan, build, implement, migrate, refactor, setup, 단계별 - -### → Debate & Critic -- "비교해줘", "뭐가 나을까", "토론해줘", "장단점", "선택해줘" -- Keywords: compare, debate, discuss, trade-off, vs, 어떤 걸, 장단점 - -### → Generator-Evaluator -- "생성해줘", "작성해줘", "리뷰해줘", "평가해줘", "개선해줘" -- Keywords: generate, write, review, evaluate, improve, draft, 초안 - -### → Code Generation -- "코드 설계해줘", "설계하고 구현해줘", "코드 작성하고 리뷰해줘", "API 만들고 리뷰해줘", "코드 짜줘" -- End-to-end code creation: design → implement → review -- Keywords: 설계, design, architect, code review, 코드 생성, implement and review, 구현하고 리뷰, build and review +| Pattern | Trigger phrases / keywords | +|---------|----------------------------| +| **Planner-Executor** | 계획·구현·만들어·셋업·마이그레이션·리팩토링 / plan, build, implement, migrate, refactor, setup, 단계별 | +| **Debate & Critic** | 비교·뭐가 나을까·토론·장단점·선택 / compare, debate, trade-off, vs, 어떤 걸 | +| **Generator-Evaluator** | 생성·작성·리뷰·평가·개선 / generate, write, review, evaluate, improve, draft, 초안 | +| **Code Generation** | 설계하고 구현·코드 작성하고 리뷰·코드 짜줘 (design→implement→review) / 설계, architect, code review, 코드 생성 | ### → Ambiguous If the intent is unclear, ask the user: @@ -58,27 +44,10 @@ If the intent is unclear, ask the user: ## Execution Flow -1. **Receive** — 사용자 요청을 받는다 -2. **Analyze** — 요청의 핵심 의도를 파악한다 -3. **Select** — 위 Heuristics에 따라 패턴을 선택한다 -4. **Announce** — 선택한 패턴과 이유를 한 줄로 알려준다 -5. **Execute** — 아래 단일 정책으로 패턴을 실행한다: - - **위임 우선**: 선택한 패턴의 전용 에이전트 파일(`.github/agents/.agent.md`)이 - 있으면 `task` 도구로 해당 에이전트에 위임한다. - - **인라인 fallback**: 전용 패턴 에이전트가 없을 때만 선택한 패턴의 각 단계(역할)를 - 순서대로 직접 수행한다. 이때도 전용 커스텀 에이전트가 있는 단계(코드 리뷰 → - `reviewer`, 환경/런타임 진단 → `debugger`)는 해당 에이전트에 위임한다. - -## Rules - -- **패턴의 단계 순서를 정확히 따른다.** 계획 → 실행 → 검증처럼 각 단계의 역할을 명확히 구분해 수행한다. -- 전용 패턴 에이전트(`planner_executor`, `debate_critic`, `generator_evaluator`, `code_generation`)가 - 있으면 항상 `task` 도구로 위임하여 실행한다. 전용 패턴 에이전트가 없을 때만 인라인으로 - 직접 수행하며, 직접 시뮬레이션하거나 역할극 하지 말 것. -- 리뷰·진단처럼 전용 에이전트가 정의된 작업은 직접 흉내내지 말고 해당 에이전트에 위임한다. -- 사용자가 명시적으로 패턴을 지정하면 분석 없이 바로 해당 패턴을 사용한다. - -### AGENTS.md +1. **Analyze & Select** — 핵심 의도를 파악해 Heuristics로 패턴을 고른다. 사용자가 패턴을 명시하면 분석 없이 그대로 사용한다. +2. **Announce** — 선택한 패턴과 이유를 한 줄로 알린다. +3. **Execute** — 패턴의 단계 순서(예: 계획 → 실행 → 검증)를 정확히 지켜 실행한다: + - **위임 우선**: 전용 패턴 에이전트(`planner_executor`·`debate_critic`·`generator_evaluator`·`code_generation`)가 있으면 항상 `task` 도구로 위임한다. 직접 시뮬레이션·역할극 금지. + - **인라인 fallback**: 전용 패턴 에이전트가 없을 때만 각 단계를 직접 수행하되, 전용 에이전트가 있는 단계(코드 리뷰 → `reviewer`, 환경/런타임 진단 → `debugger`)는 그 에이전트에 위임한다. -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before -executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/planner_executor.agent.md b/.github/agents/planner_executor.agent.md index b057501..b6094ed 100644 --- a/.github/agents/planner_executor.agent.md +++ b/.github/agents/planner_executor.agent.md @@ -18,19 +18,6 @@ You are the **Planner-Executor Coordinator** for this project. ### Routing: Plan → Execute → Validate 순환 -```mermaid -graph TD - Start[요구사항 정의] --> Plan[Planner: 실행 계획 수립] - Plan --> Exec[Executor: 태스크 구현] - Exec --> Val[Validator: 검증] - Val --> D{Pass?} - D -->|Yes| Next{남은 태스크?} - D -->|No / Revise| Plan - Next -->|Yes| Exec - Next -->|No| Done[전체 완료] - Done --> Doc[Scribe: 문서화] -``` - 1. **Planner** → 실행 계획 수립 (태스크 목록 + 의존성 + 완료 기준) 2. **Executor** → 태스크 1부터 순서대로 구현 3. **Validator** → 완료된 태스크 검증 @@ -46,6 +33,4 @@ graph TD - 최대 Revise 횟수는 3회. 초과 시 현재 상태로 종료하고 Scribe가 기록한다. - 사용자 요청을 받으면 즉시 어떤 에이전트를 스폰하는지 간단히 알려준 후 작업을 시작한다. -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/agents/reviewer.agent.md b/.github/agents/reviewer.agent.md index ff59c76..b84739b 100644 --- a/.github/agents/reviewer.agent.md +++ b/.github/agents/reviewer.agent.md @@ -30,6 +30,4 @@ tools: ["read", "search"] - 파일명과 줄번호를 명시한다. - 심각도를 표시한다: 🔴 필수 수정 / ⚠️ 권장 / 💡 제안 -### AGENTS.md - -This project has an `AGENTS.md` harness at the repo root. Read it and follow all rules before executing any git or external commands. +> Follow the root `AGENTS.md` harness rules before running any git or external command. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index fa31f1f..8c7c47c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -13,8 +13,7 @@ 3. **GroupChat 워크플로우** (`03_group_chat.py`) — 여러 에이전트가 협업 토론 4. **동시(Concurrent) 워크플로우** (`04_concurrent_workflow.py`) — 여러 전문가가 병렬 검토 5. **MCP 도구 연동** (`05_mcp_agent.py`) — `MCPStreamableHTTPTool`로 외부 시스템 호출 -6. **RAG** (`06_rag_agent.py`, `06_rag_agent_foundry_iq.py`) — 검색 증강 생성 - (기본 버전과 Foundry IQ 버전 2가지 변형 제공) +6. **RAG** (`06_rag_agent.py`, `06_rag_agent_foundry_iq.py`) — 검색 증강 생성 (기본 + Foundry IQ 변형) ## 기술 스택 @@ -27,16 +26,12 @@ ## 프로젝트 코드 패턴 -코드 생성 시 이 프로젝트의 기존 패턴을 따른다: +코드 생성 시 기존 패턴을 따른다 (상세 API는 `agent-framework-codegen` 스킬 참조): -- Chat 클라이언트는 `FoundryChatClient(project_endpoint=..., model=..., credential=...)`로 생성 (키워드 인자) -- 에이전트는 `Agent(client=client, name=..., instructions=...)`로 생성하고(모든 인자 키워드 형태), 역할은 `instructions`로 부여 -- Sequential은 `SequentialBuilder(participants=[...]).build()`로 순차 파이프라인 구성 -- GroupChat은 `GroupChatBuilder(participants=..., selection_func=..., max_rounds=...).build()` -- Concurrent는 `ConcurrentBuilder(participants=[...]).build()`로 병렬 검토 구성 -- 모든 진입점은 `if __name__ == "__main__": asyncio.run(main())` -- 환경변수는 `load_dotenv`로 로드하고, `PROJECT_ENDPOINT` 누락 시 친절한 오류 후 종료 -- 새 예제는 `src/`에 `NN_.py` 규칙으로 추가한다 +- 클라이언트·에이전트는 키워드 인자로 생성: `FoundryChatClient(project_endpoint=..., model=..., credential=...)`, `Agent(client=..., name=..., instructions=...)` (역할은 `instructions`로 부여) +- 오케스트레이션: `SequentialBuilder(participants=[...])`, `GroupChatBuilder(participants=..., selection_func=..., max_rounds=...)`, `ConcurrentBuilder(participants=[...])` 뒤에 `.build()` +- 진입점은 `if __name__ == "__main__": asyncio.run(main())`, 환경변수는 `load_dotenv`로 로드하고 `PROJECT_ENDPOINT` 누락 시 친절한 오류 후 종료 +- 새 예제는 `src/`에 `NN_.py` 규칙으로 추가 ## Agent Framework 코드 생성 diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index cff6bad..c86835b 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -6,27 +6,18 @@ applyTo: "**/*.py" ## 가상환경 설정 -- Python 3.14.5 기반 `.venv` 가상환경을 사용한다. -- 권장 버전은 Python 3.14.5이다. -- 가상환경 생성 및 활성화: +- Python 3.14.5 기반 `.venv` 가상환경을 사용한다 (`.venv/`는 `.gitignore`로 버전 관리에서 제외). +- 생성·활성화 후 가상환경 안에서 패키지를 설치한다: ```bash python -m venv .venv - source .venv/bin/activate # macOS / Linux - # .venv\Scripts\activate # Windows - ``` -- 패키지 설치는 가상환경 활성화 후 진행한다: - ```bash + source .venv/bin/activate # macOS/Linux (Windows: .venv\Scripts\activate) pip install -r requirements.txt ``` -- `.venv/` 디렉토리는 `.gitignore`에 포함하여 버전 관리에서 제외한다. ## 의존성 관리 -- 프로젝트 의존성은 `requirements.txt`에 명시한다. -- 새 패키지를 추가하면 `requirements.txt`를 갱신한다. -- **SDK·핵심 패키지는 `==` 또는 `>=x,=` 형태의 최소 버전 지정도 허용한다.** -- 일반 라이브러리를 추가할 때도 버전 범위를 명시해 재현 가능성을 유지한다. +- 의존성은 `requirements.txt`에 명시하고, 패키지를 추가하면 갱신한다. +- 재현성을 위해 버전을 명시한다: SDK·핵심 패키지는 `==` 또는 `>=x,=` 최소 버전 지정도 허용. ## 코드 컨벤션 diff --git a/.github/prompts/add-agent.prompt.md b/.github/prompts/add-agent.prompt.md index 90c9365..1f575bf 100644 --- a/.github/prompts/add-agent.prompt.md +++ b/.github/prompts/add-agent.prompt.md @@ -26,23 +26,9 @@ mode: "agent" ## 규칙 -- 기존 예제의 구조를 따른다: - ```python - project_endpoint = os.getenv("PROJECT_ENDPOINT") - if not project_endpoint: - print("오류: PROJECT_ENDPOINT 환경 변수를 설정해주세요.") - sys.exit(1) - client = FoundryChatClient( - project_endpoint=project_endpoint, - model=os.getenv("MODEL_DEPLOYMENT_NAME", "gpt-5.4"), - credential=AzureCliCredential(), - ) - agent = Agent(client=client, name="...", instructions="...") - ``` +- 공통 골격(`FoundryChatClient`+`Agent` 생성, `PROJECT_ENDPOINT` 검증 후 한국어 오류 + `sys.exit(1)`, import 경로)은 `agent-framework-codegen` 스킬을 따른다 - 모든 호출은 `async/await`, 진입점은 `asyncio.run(main())` -- `PROJECT_ENDPOINT` 누락 시 한국어 오류 메시지 후 `sys.exit(1)` -- **스트리밍 출력**: 단일 에이전트는 `from _streaming import stream_agent`를, 워크플로우는 - `from _streaming import stream_workflow`를 사용한다 (`agent.run()` 직접 print 금지) +- **스트리밍 출력**: 단일 에이전트는 `from _streaming import stream_agent`, 워크플로우는 + `from _streaming import stream_workflow` (`agent.run()` 직접 print 금지) - `instructions`와 콘솔 출력은 한국어로 작성 - 무한 루프 방지를 위해 워크플로우에는 `max_rounds`/수렴 조건을 둔다 -- 작성 후 `agent-framework-codegen` 스킬의 API 규칙과 일치하는지 확인 diff --git a/.github/skills/agent-framework-codegen/SKILL.md b/.github/skills/agent-framework-codegen/SKILL.md index e2ba86d..4e2f8a4 100644 --- a/.github/skills/agent-framework-codegen/SKILL.md +++ b/.github/skills/agent-framework-codegen/SKILL.md @@ -304,12 +304,9 @@ result = await agent.run(augmented) # 3) 생성 |------|-------------| | `PROJECT_ENDPOINT 환경 변수를 설정해주세요` | 루트 `.env` 작성 + `load_dotenv` 경로 확인 | | 인증 실패 | `az login` 재실행, `az account set`으로 구독 선택 | -| 의도치 않은 handoff 경로가 보임 | 기본 mesh topology 적용 상태 — 필요한 경로만 허용하려면 `add_handoff(from, [to...])`로 제한 | | `400 Invalid 'tools[0].name'` (handoff) | Agent `name`에 한글/공백 사용 — handoff 도구명은 ASCII(`^[a-zA-Z0-9_.-]+$`)만 허용. name을 영문으로 변경 | | Handoff `build()`가 `ValueError`(persistence) | 일부 Agent에 `require_per_service_call_history_persistence=True` 누락 — 모든 참여 Agent에 지정 | | GroupChat이 끝나지 않음 | `max_rounds` 또는 `termination_condition` 미설정 | | GroupChat 결과가 종료 메시지만 나옴 | `get_outputs()`는 종료 메시지만 반환 — 토론 내용은 이벤트의 `AgentExecutorResponse`에서 추출 | | `WorkflowBuilder` `Case` 조건이 항상 첫 케이스로만 분기됨 | 조건은 **순서대로 평가**되며 첫 번째 `True`에서 멈춤 — 조건 순서를 좁은 것부터 배치할 것 | -| MCP 도구를 호출하지 않음 | `tools=` 전달 누락, 또는 `async with mcp_tool:` 밖에서 실행 | -| RAG가 엉뚱한 답을 함 | 검색 결과가 빈약하거나 "문서 밖 추측 금지" 지시문 누락 | | `ImportError: agent_framework...` | `pip install -U agent-framework`, 가상환경 활성화 확인 |