diff --git a/AGENTS.md b/AGENTS.md index e7a4851..f0ad5ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ +Read and follow [Engineering-Prompt.md](Engineering-Prompt.md) before starting work in this project. + Read [operating instructions](docs/OPERATING_INSTRUCTIONS.md), then [project instructions](docs/PROJECT_INSTRUCTIONS.md). These shared documents are authoritative for every agent. Edit them instead of forking per-tool guidance. diff --git a/CLAUDE.md b/CLAUDE.md index e7a4851..f0ad5ee 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,5 @@ +Read and follow [Engineering-Prompt.md](Engineering-Prompt.md) before starting work in this project. + Read [operating instructions](docs/OPERATING_INSTRUCTIONS.md), then [project instructions](docs/PROJECT_INSTRUCTIONS.md). These shared documents are authoritative for every agent. Edit them instead of forking per-tool guidance. diff --git a/Engineering-Prompt.md b/Engineering-Prompt.md new file mode 100644 index 0000000..17782a2 --- /dev/null +++ b/Engineering-Prompt.md @@ -0,0 +1,125 @@ +Before implementing anything, follow a **reuse-first / ecosystem-first engineering approach**. + +Your job is not merely to make the feature work. Your job is to solve it using the **smallest, most standard, most maintainable solution that already exists** whenever possible. + +## Mandatory reconnaissance before writing code + +Before designing or implementing a custom solution: + +1. **Inspect the existing codebase** + - Understand the current architecture and conventions. + - Identify existing abstractions, utilities, services, packages, SDKs, helpers, patterns, and extension points that are relevant. + - Prefer extending existing code over creating parallel implementations. + - Check dependency manifests and determine what libraries/SDKs are already installed and what versions are pinned. + +2. **Investigate existing SDK/library capabilities** + - Check whether an SDK or package we already use supports the required functionality. + - Do not assume the currently pinned version represents the latest capabilities. + - Check newer versions, release notes, migration guides, API references, generated docs, and examples. + - If a newer SDK version solves the problem cleanly, evaluate upgrading it before implementing the capability ourselves. + - A major-version bump is not automatically disqualifying. Evaluate the actual migration cost and breaking changes. + +3. **Search the broader ecosystem** + - Search GitHub for existing implementations, issues, discussions, examples, reference projects, and upstream solutions. + - Check official repositories before random third-party examples. + - Look for maintained packages, SDKs, framework integrations, plugins, extensions, adapters, and tools that already solve the problem. + - Check package registries relevant to the stack: npm, NuGet, PyPI, Go modules, Maven, Cargo, etc. + - Check available ChatGPT/Codex plugins, skills, tools, MCP servers, or connected services when they can provide the capability directly. + +4. **Check the platform/framework standard library** + - Before inventing infrastructure, verify whether the language or framework already provides it. + - Prefer standard facilities for HTTP, testing, mocking, serialization, retries, caching, dependency injection, logging, authentication, configuration, concurrency, etc. + - Example: do not create a custom HTTP-client abstraction merely to make tests possible if the language's normal HTTP testing utilities already support the requirement. + +## Preferred solution hierarchy + +Use this order of preference: + +Existing codebase capability +→ Existing dependency capability +→ Upgrade an existing dependency +→ Official SDK/library/package +→ Standard library/framework feature +→ Well-maintained community package +→ Small adapter around one of the above +→ Custom implementation + +A custom implementation should be the **last resort**, not the starting point. + +## Before choosing custom code + +If you believe a custom implementation is necessary, explicitly explain: + +- What existing code you inspected. +- Which SDKs/packages you evaluated. +- Whether newer versions contain the capability. +- Which official docs/repositories/GitHub issues you checked. +- Why existing solutions are insufficient. +- Why extending or upgrading an existing dependency is worse. +- What maintenance burden the custom implementation introduces. + +If you cannot provide a convincing answer to those questions, **continue researching instead of writing the custom implementation**. + +## Avoid accidental infrastructure + +Be especially suspicious if your solution starts requiring custom versions of foundational infrastructure such as: + +- HTTP clients +- retry frameworks +- authentication clients +- serialization layers +- logging frameworks +- test/mocking frameworks +- dependency injection systems +- caching systems +- database clients +- API clients that duplicate an official SDK + +These are strong signals that you may be solving the problem at the wrong abstraction level. + +## Optimize for engineering taste, not code volume + +Do not reward yourself for writing more code. + +Prefer solutions that: + +- reduce code ownership +- reduce maintenance burden +- follow existing project conventions +- use battle-tested libraries +- minimize new abstractions +- minimize surface area +- remain easy for another senior engineer to understand +- make future upgrades easier rather than harder + +Do not create an abstraction merely because it makes the implementation look architecturally complete. + +## Research before implementation + +For non-trivial tasks, do not immediately start modifying files. + +First produce a short **reconnaissance summary** containing: + +**Existing:** What relevant capabilities already exist in the repository. + +**Ecosystem:** Relevant SDKs, packages, standard-library features, plugins, skills, or upstream implementations you found. + +**Upgrade path:** Whether updating an existing dependency would solve the problem. + +**Recommendation:** The simplest approach and why. + +**Rejected alternatives:** Any tempting custom approaches and why they are unnecessary. + +**Do not begin implementation until the reconnaissance phase is complete.** + +## Final sanity check + +Immediately before implementing, ask: + +> "Am I writing code that someone else has already written, maintained, tested, documented, and packaged for this exact ecosystem?" + +If the answer might be yes, investigate that option first. + +The goal is: + +**Use what exists. Extend before replacing. Upgrade before reimplementing. Wrap before rebuilding. Own as little infrastructure as possible.**