Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (53 loc) · 3.75 KB

AGENTS.md

File metadata and controls

68 lines (53 loc) · 3.75 KB
Raw

atframe_utils Agent Guide

This is the canonical, self-contained cross-agent guide for this repository. Keep it short: put repeatable workflows in .agents/skills/*/SKILL.md, keep CLAUDE.md as a lightweight bridge, and avoid redundant tool-specific prompt copies. This repository manages its own AI agent prompts and skills; it must not depend on a parent or sibling repository guide.

atframe_utils is a C++ utility library for algorithms, crypto, logging, memory, networking, and common runtime helpers.

Project Map

  • include/: public headers (algorithm, common, log, memory, network, nostd, time, etc.).
  • src/: implementation files.
  • test/: private unit test framework and test cases.
  • sample/, tools/: examples and utilities.
  • .agents/skills/: build, testing, and AI-agent maintenance playbooks.

Always-On Rules

  • Respect the user's dirty workspace: inspect current file contents before editing and avoid unrelated reformatting.
  • Resolve <BUILD_DIR> before creating build trees or temporary files: read the nearest .vscode/settings.json for cmake.buildDirectory; if absent, infer from clangd --compile-commands-dir=... or an existing configured build tree; if no user setting is readable, use build.
  • Put all CMake build trees, AI scratch files, script output/logs, and temporary data under <BUILD_DIR>/...; for agent scratch use <BUILD_DIR>/_agent_tmp/.... Never create ad-hoc temp files in the repository root.
  • Read the matching .agents/skills/*/SKILL.md before build or test work; skills contain commands and edge cases.
  • After C++ edits, run clang-format -i <file> and verify with clang-format --dry-run --Werror <file> when practical.

C++ Conventions

  1. Namespace: public code is under atfw::util.

  2. Include guards: use #pragma once.

  3. Header code: any function, method, friend, or operator body written in a header must use ATFW_UTIL_FORCEINLINE; avoid plain inline for project code unless matching generated or third-party code.

  4. Exported ABI: interfaces declared with ATFRAMEWORK_UTILS_API or other *_API export macros must be implemented in .cpp files, not headers, so ABI stays stable across compilers and build options.

  5. Naming: classes/functions use snake_case; constants use UPPER_SNAKE_CASE; member variables use trailing _.

  6. Error handling: use return codes or nostd::result types as existing code does.

  7. Anonymous namespace + static: in .cpp files, file-local functions should be inside an anonymous namespace and keep the static keyword.

    namespace {
static void my_helper() { /* ... */ }
}  // namespace

Skill Routing

Read the matching .agents/skills/*/SKILL.md before specialized work:

Skill Use when
build Configuring or building with CMake
testing Running or writing private test-framework cases
ai-agent-maintenance Auditing or optimizing AI agent prompts, bridge files, and skills

Agent File Compatibility

  • AGENTS.md is canonical for tools that support hierarchical agent instructions.
  • .agents/skills/ is the portable project skill location; keep each SKILL.md focused and self-contained.
  • Do not maintain .github/copilot-instructions.md copies when AGENTS.md and .agents/skills/ cover the same rules.
  • CLAUDE.md exists only to point Claude-compatible tools at this guide and .agents/skills/.
  • Do not make this repository depend on root, sibling, or vendored-submodule prompt files.
  • Keep skill folder names and frontmatter name values identical; descriptions are the discovery surface.