docs: спроектировать Codex-агент поиска SDK

2026-07-17 01:06:25 +03:00
parent 7cb44a073e
commit 6aa05b1adb
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Codex SDK Research Agent Design
+
+## Goal
+
+Adapt the project-scoped `kompas-sdk-research` custom agent for Codex while
+leaving the Claude Code agent unchanged. The Codex agent must be optimized for
+fast, read-heavy searches in the local KOMPAS SDK Markdown knowledge base and
+must not modify the workspace.
+
+## Configuration
+
+The Codex agent remains in `.codex/agents/kompas-sdk-research.toml` and uses:
+
+```toml
+name = "kompas-sdk-research"
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+```
+
+`gpt-5.6-terra` fits exploration, documentation scans, and distilled support
+work. Medium reasoning is used because SDK questions can require correlating
+several interfaces, overloads, constants, and COM call-chain details.
+
+## Agent Responsibilities
+
+The agent searches only local project and installed SDK reference material:
+
+- `docs/Kompas3D_SDK/` is the canonical source for COM API5/API7 documentation.
+- SDK headers under the installed KOMPAS SDK may be read when exact constant
+  values need confirmation.
+- The agent must not browse the web, edit files, implement features, or build
+  geometry in KOMPAS-3D.
+- KsAPI is outside the Markdown knowledge base and must be reported as outside
+  scope instead of guessed.
+
+The parent agent delegates non-trivial SDK lookups before implementation. It
+remains responsible for validating interop-specific discrepancies through
+reflection over `libs/kompas-interop/*.dll` when needed.
+
+## Prompt Adaptation
+
+Remove Claude-specific references to Haiku and Opus from the Codex TOML. Keep
+the existing domain guidance, but express it in provider-neutral Codex terms.
+The description must make proactive delegation triggers clear without claiming
+that the agent uses tools or model behavior specific to Claude Code.
+
+The response contract remains concise and evidence-oriented:
+
+1. Relevant interface, method, property, enum, or constant.
+2. Automation syntax and COM syntax when parameter ordering matters.
+3. Parameter and return-value meanings, including units and side effects.
+4. Related overloads or interfaces when relevant.
+5. Source article path and its `sources` frontmatter entry.
+6. A warning when generated .NET interop names may differ from SDK docs.
+
+## Isolation and Compatibility
+
+The Claude definition in `.claude/agents/kompas-sdk-research.md` is not changed.
+The two versions intentionally use different configuration formats and model
+selection while sharing the same research methodology.
+
+The Codex agent's read-only behavior is enforced by `sandbox_mode`, not merely
+requested in prose. No exact Claude-style tool allowlist is copied into the
+Codex configuration.
+
+## Verification
+
+After editing the TOML:
+
+- parse it as TOML;
+- confirm the required fields and selected model settings;
+- confirm `sandbox_mode = "read-only"`;
+- search the Codex file for stale `Haiku`, `Opus`, and Claude-specific wording;
+- confirm the Claude agent file is unchanged.