에이전트 선택적 탐색 구조 개선과 경고 정리 반영

- claude-code 선택적 탐색 흐름을 참고해 Cowork/Code 시스템 프롬프트에서 folder_map 상시 선행 지시를 완화하고 glob/grep 기반 좁은 탐색을 우선하도록 조정함

- FolderMapTool 기본 depth를 2로, include_files 기본값을 false로 낮추고 MultiReadTool 최대 파일 수를 8개로 줄여 초기 과탐색 폭을 보수적으로 조정함

- AgentLoopExplorationPolicy partial을 추가해 탐색 범위 분류, broad-scan corrective hint, exploration_breadth 성능 로그를 연결함

- AgentLoopService에 탐색 범위 가이드 주입과 실행 중 탐색 폭 추적을 추가하고, 좁은 질문에서 반복적인 folder_map/대량 multi_read를 교정하도록 정리함

- DocxToHtmlConverter nullable 경고를 수정해 Release 빌드 경고 0 / 오류 0 기준을 다시 충족함

- README와 docs/DEVELOPMENT.md에 2026-04-09 10:36 (KST) 기준 개발 이력을 반영함

src/AxCopilot/Services/Agent/AgentLoopExplorationPolicy.cs

@@ -0,0 +1,154 @@
+using System.Text.Json;
+using AxCopilot.Models;
+
+namespace AxCopilot.Services.Agent;
+
+public partial class AgentLoopService
+{
+    private enum ExplorationScope
+    {
+        Localized,
+        TopicBased,
+        RepoWide,
+        OpenEnded,
+    }
+
+    private sealed class ExplorationTrackingState
+    {
+        public ExplorationScope Scope { get; init; }
+        public int FolderMapCalls { get; set; }
+        public int TotalFilesRead { get; set; }
+        public int MultiReadFilesRead { get; set; }
+        public bool BroadScanDetected { get; set; }
+        public bool SelectiveHit { get; set; }
+        public bool CorrectiveHintInjected { get; set; }
+    }
+
+    private static ExplorationScope ClassifyExplorationScope(string userQuery, string? activeTab)
+    {
+        if (string.IsNullOrWhiteSpace(userQuery))
+            return ExplorationScope.OpenEnded;
+
+        var q = userQuery.Trim();
+        var lower = q.ToLowerInvariant();
+
+        if (lower.Contains("전체") || lower.Contains("전반") || lower.Contains("코드베이스 전체") ||
+            lower.Contains("repo-wide") || lower.Contains("repository-wide") || lower.Contains("전체 구조") ||
+            lower.Contains("아키텍처") || lower.Contains("전체 점검"))
+            return ExplorationScope.RepoWide;
+
+        if (q.Contains('.') || q.Contains('/') || q.Contains('\\') ||
+            lower.Contains("file ") || lower.Contains("class ") || lower.Contains("method ") ||
+            lower.Contains("function ") || lower.Contains("line ") || lower.Contains("bug") ||
+            lower.Contains("오류") || lower.Contains("버그") || lower.Contains("예외"))
+            return ExplorationScope.Localized;
+
+        if (lower.Contains("정리") || lower.Contains("요약") || lower.Contains("보고서") ||
+            lower.Contains("주제") || lower.Contains("관련") || lower.Contains("분석"))
+            return ExplorationScope.TopicBased;
+
+        return string.Equals(activeTab, "Code", StringComparison.OrdinalIgnoreCase)
+            ? ExplorationScope.Localized
+            : ExplorationScope.OpenEnded;
+    }
+
+    private static void InjectExplorationScopeGuidance(List<ChatMessage> messages, ExplorationScope scope)
+    {
+        var guidance = scope switch
+        {
+            ExplorationScope.Localized =>
+                "Exploration scope = localized. Start with grep/glob and targeted file reads. Avoid folder_map unless structure is unclear.",
+            ExplorationScope.TopicBased =>
+                "Exploration scope = topic-based. Identify candidate files by topic keywords first, then read only a small targeted set.",
+            ExplorationScope.RepoWide =>
+                "Exploration scope = repo-wide. Broad structure inspection is allowed when needed.",
+            _ =>
+                "Exploration scope = open-ended. Expand gradually. Prefer selective discovery before broad scans."
+        };
+
+        messages.Add(new ChatMessage
+        {
+            Role = "system",
+            Content = guidance
+        });
+    }
+
+    private static int CountMultiReadPaths(string argsJson)
+    {
+        try
+        {
+            using var doc = JsonDocument.Parse(argsJson);
+            if (doc.RootElement.TryGetProperty("paths", out var pathsEl) && pathsEl.ValueKind == JsonValueKind.Array)
+                return pathsEl.GetArrayLength();
+        }
+        catch
+        {
+        }
+
+        return 0;
+    }
+
+    private static bool ShouldInjectExplorationCorrection(
+        ExplorationTrackingState state,
+        string toolName,
+        string argsJson)
+    {
+        if (state.Scope is ExplorationScope.RepoWide or ExplorationScope.OpenEnded)
+            return false;
+
+        if (state.FolderMapCalls >= 2)
+            return true;
+
+        if (state.MultiReadFilesRead >= 6 || state.TotalFilesRead >= 8)
+            return true;
+
+        if (string.Equals(toolName, "folder_map", StringComparison.OrdinalIgnoreCase))
+        {
+            try
+            {
+                using var doc = JsonDocument.Parse(argsJson);
+                var includeFiles = doc.RootElement.TryGetProperty("include_files", out var includeFilesEl) &&
+                                   includeFilesEl.ValueKind is JsonValueKind.True or JsonValueKind.False &&
+                                   includeFilesEl.GetBoolean();
+                var depth = doc.RootElement.TryGetProperty("depth", out var depthEl) && depthEl.ValueKind == JsonValueKind.Number
+                    ? depthEl.GetInt32()
+                    : 2;
+                if (includeFiles || depth >= 3)
+                    return true;
+            }
+            catch
+            {
+            }
+        }
+
+        return false;
+    }
+
+    private static void TrackExplorationToolUse(
+        ExplorationTrackingState state,
+        string toolName,
+        string argsJson)
+    {
+        if (string.Equals(toolName, "folder_map", StringComparison.OrdinalIgnoreCase))
+        {
+            state.FolderMapCalls++;
+            return;
+        }
+
+        if (string.Equals(toolName, "multi_read", StringComparison.OrdinalIgnoreCase))
+        {
+            var count = CountMultiReadPaths(argsJson);
+            state.MultiReadFilesRead += count;
+            state.TotalFilesRead += count;
+            if (count >= 6)
+                state.BroadScanDetected = true;
+            return;
+        }
+
+        if (string.Equals(toolName, "file_read", StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(toolName, "document_read", StringComparison.OrdinalIgnoreCase))
+        {
+            state.TotalFilesRead++;
+        }
+    }
+}