Skip to content

AGENTS.md

Latest commit

 

History

History
137 lines (104 loc) · 5.76 KB

AGENTS.md

File metadata and controls

137 lines (104 loc) · 5.76 KB
Raw

AGENTS

This repository is a header-only C++ logging library with optional tests, examples, and benchmarks. Keep agent instructions focused on log-it-cpp itself rather than on generic product or application architecture.

Always Follow

  • Keep diffs minimal and focused.
  • Do not refactor or apply style changes beyond the lines you directly touch.
  • Use Conventional Commits: type(scope): summary.
  • Commit headers must be in English and include a descriptive body.

Codebase Discovery

For non-trivial codebase investigation, architecture questions, cross-file edits, refactors, call chains, or unknown implementation locations, use Codebase Memory before Grep/Glob/Read/LSP.

Preferred sequence: index_status → search_graph / trace_path / get_code_snippet → targeted Read/LSP.

Grep/Glob are fallback or precision-confirmation tools, not first-pass architecture discovery.

Public Entry Headers

Use the project umbrella headers instead of recreating include order manually:

  • include/logit_cpp/logit.hpp - full library entry point.
  • include/logit_cpp/logit/utils.hpp - utilities module umbrella.
  • include/logit_cpp/logit/formatter.hpp - formatter module umbrella.
  • include/logit_cpp/logit/loggers.hpp - logger backend umbrella.

These headers prepare internal dependencies in the intended order.

<logit.hpp> is the supported application entry point. Module umbrellas are supported for focused use; logit/log_macros.hpp is an aggregate-owned macro implementation header and has no standalone-inclusion guarantee. A leaf type header is standalone only when its documentation and include-contract test say so. Public aliases such as logit::QueuePolicy are normally consumed through <logit.hpp> or the relevant module umbrella.

Include Policy

  • Do not use ../ in #include directives.
  • Within a module (logit/utils/*, logit/formatter/*, logit/loggers/*) include only headers from the same sub-tree using forward paths.
  • Cross-module dependencies must come through the nearest umbrella header instead of direct sibling includes.
  • Files under logit/detail/ may include other detail headers, but must not include public logit/... headers.
  • Prefer the self-contained public entry points in include/logit_cpp.

Header Naming

  • If a header defines one primary class, use a PascalCase filename.
  • If a header contains mixed declarations, helpers, macros, or multiple types, use a snake_case filename.

Scoped Instructions

Read the nearest module guide before editing files in that tree. These guides keep public-header, test, example, documentation, and agent-workflow rules close to the code they govern:

When a change crosses module boundaries, follow all applicable guides and record the public contract in the narrowest relevant document. Do not copy the same rule into every guide.

Review Checklist

Before submitting a change, inspect both enabled and disabled compile-time paths. In particular, check that noexcept functions cannot allocate, invoke user callbacks, or propagate exceptions; that conditions are reachable and not permanently true or false; that repeated logic has a single owner; and that optional dependencies do not break a default build or package export. Run the focused tests plus the relevant CMake configure/build flow and report platform-only failures explicitly.

Header Guards

For every project-owned C/C++ header, use #pragma once together with a non-reserved include guard. Guard names must be derived from the project prefix and header path, and must clearly indicate that the macro is a header guard:

LOGIT_CPP_HEADER_<PATH>_<FILE>_<EXT>_INCLUDED

Do not use identifiers reserved for the compiler, standard library, platform SDK, or other implementation internals. In particular, do not use include guard names that start with an underscore, start with an underscore followed by an uppercase letter, or contain a double underscore anywhere.

Implementation fragments such as .ipp, .inl, or .tpp files may remain unguarded if they are only included from already guarded headers and are not intended for direct inclusion. If they are intended to be included directly, they must follow the same non-reserved guard naming rule.

Repository Setup

Before configuring or building, initialize submodules:

git submodule update --init --recursive

Detailed Playbooks

Read the matching file in guides/ when the task needs more detail:

  • guides/README.md - index of available agent instructions.
  • guides/orientation.md - project map, subsystem model, extension recipes, and safety invariants for AI agents.
  • guides/commits.md - commit message rules.
  • guides/cpp_style.md - naming and style guidance.
  • guides/header-impl.md - .hpp / .ipp / .tpp ownership and include-structure rules.
  • guides/header-impl-RU.md - Russian localization of the header ownership playbook.
  • guides/logging-macros.md - macro-first logging guidance for normal application code and agent behavior.
  • guides/concurrency.md - thread-safety contracts, callback dispatch, mutex ordering, and shutdown invariants.
  • guides/build.md - submodules, configure/build/test/bench flow.
  • guides/ci.md - CI environment parity, toolchain compatibility, sanitizer/timing test guidance, and CI-failure workflow.