engineering-guidelines

name	engineering-guidelines
description	Use when: writing or reviewing C++, public headers, template function visibility, exported API ABI, ATFW_UTIL_SYMBOL_VISIBLE, or ATFW_UTIL_FORCEINLINE.

Engineering Guidelines

Use this skill before writing or reviewing C++ in atframe_utils.

Header and ABI boundaries

• Classify each interface as public library API or non-exported internal code before choosing a visibility marker.
• Every public non-template API must use ATFRAMEWORK_UTILS_API (or its matching *_API macro) on the declaration or enclosing type, or use ATFW_UTIL_FORCEINLINE for a header definition. Plain/implicit inline and constexpr alone do not satisfy this public-API rule.
• A public template function defined in a header may instead use ATFW_UTIL_SYMBOL_VISIBLE: a non-inlined instantiation can share one visible copy across linked targets, while an inlined call embeds a per-target copy. Keep the definition ODR-identical for every consumer so all copies have identical behavior.
• Keep non-template implementations covered by an export macro in .cpp files by default.
• Non-exported internal helpers may use ODR-correct implicit inline, constexpr, or intentional plain inline.

Review and validation

• For touched public headers, verify the publication model, template visibility, and ODR-identical definition together.
• Preserve generated and third-party code unless its source of truth is in scope.
• Run clang-format for changed C++ files and git diff --check for the scoped changes.