Imported from Xlucidator/Nearlighter (
AGENTS.md). Install upstream withnpx skills add Xlucidator/Nearlighter. Copyright stays with the author.
AGENTS.md
Project Context
- Nearlighter is a learning-oriented CPU path tracer based on the Ray Tracing in One Weekend series.
- Current priority is project cleanup and optimization before adding larger rendering features.
- Code layout: public headers in
include/nearlighter/, implementations insrc/, and submodules inthirdparty/. - Key docs:
README.md,scripts/README.md,tests/README.md, anddocs/.
Documentation and Output Conventions
- Communicate with the user and write user-facing documentation in Chinese.
- Code, code comments, identifiers, commit messages, and agent-facing technical notes should use plain English.
- Keep explanations concrete and engineering-focused. Avoid decorative wording and emojis.
- Use standard GitHub-Flavored Markdown for user-facing responses, terminal-oriented Markdown output, and generated Markdown documents so they render correctly in common editors.
- Write inline mathematics as
$ ... $; do not use\( ... \)delimiters. - Write display mathematics on their own lines within
$$ ... $$; do not use\[ ... \]delimiters. - Keep each multiline display formula inside one pair of
$$delimiters, and insert line breaks only where the mathematical structure requires them. - Do not prefix display formulas with meaningless Markdown headings such as
##.
Engineering Principles
- Favor semantically coherent abstractions, clear responsibility boundaries, reusable modular APIs, and simple, efficient implementations. Avoid redundant layers and generalized infrastructure without a current requirement.
- Start from requirements and first principles. Clarify unclear goals; challenge inefficient proposals and suggest better alternatives before implementation.
- Default to discussion and alignment before writing non-trivial code.
- Preserve the current project style where practical, but improve clarity, correctness, and C++ hygiene when touching code.
- Keep changes scoped. Do not mix broad refactors with feature work unless the refactor is necessary for that feature.
Planning Conventions
- Keep
ref/plans/for agreed stage-level static plans. Once implementation begins, do not rewrite them merely to record progress. - Include the stage background, objectives, scope and non-goals, current gaps, architecture and naming decisions, rationale and tradeoffs, phased work, dependencies, risks, tests, and acceptance criteria.
- Before implementation, read the static plan completely and use Plan mode for the fine-grained dynamic plan. Do not copy execution status back into the static plan.
- Store durable implementation status, deviations, and verification records under
ref/plans/status/. Material design changes require user alignment and an explicit revision or addendum.
Codebase Conventions
- Headers should include dependencies required by value members, bases, inline code, and public contracts. Forward declare only when a declaration, pointer, or reference is sufficient.
- Keep umbrella headers out of low-level module headers.
core.handio.hexpose their modules;nearlighter.hexposes the complete SDK for external convenience. - Keep meaningful parameter names in public declarations, including parameters unused by inline default implementations. Use C++17
[[maybe_unused]]when necessary; do not remove names merely to silence compiler warnings. Out-of-line definitions may omit genuinely unused names when the public declaration already documents them. - Keep established technical acronyms uppercase in identifiers, such as
AABB,BVH,PDF,PPM, andRGB. - Prefer names that express a map's domain role. Use
<key>_to_<value>when the lookup relationship needs clarification; keep natural registry or index names when context already makes the key clear. - Keep third-party code in
thirdparty/submodules and expose it through CMake targets. - Prefer target-based CMake (
target_sources,target_include_directories,target_link_libraries) over global include/link settings. - Avoid global mutable state in new rendering code, especially for random generators and output/gamma configuration.
Testing Conventions
- Test core behavior whose regressions can remain silent; skip trivial behavior and failures already obvious during normal execution.
- Keep tests small, deterministic, focused, and proportionate to the regression risk. Add coverage before changing performance-sensitive code such as BVH, sampling, or intersection routines.
- Document each test's purpose, coverage, and logic in
tests/README.mdin the same change.
Commenting Conventions
Principles
- Comment non-obvious rendering, geometry, math, ownership, numerical, coordinate-space, and error-handling logic generously.
- Explain intent, rationale, assumptions, constraints, and invariants; never restate code. Keep comments current.
- Read
ref/comment_style.mdfor detailed guidance and examples when dealing comments.
Comment Hierarchy
-
Level 1 — file, module, or class sections
- Use concise banners for recognizable responsibility groups; omit them in small single-purpose files.
- C++: file or class sections with
//; retain Doxygen on public declarations. - Python: module sections with
#; use two blank lines above except at file start and one below.
// ================================================== // Section Title // Optional relationship or structure // ==================================================# ================================================== # Section Title # ================================================== -
Level 2 — classes and functions
- C++: concise Doxygen blocks (
/** ... */) before declarations, never///; document useful contracts, invariants, ownership, and tags without duplicating them on.cppdefinitions. - Python: concise
'''...'''docstrings as the first statement; mention only useful contracts, units, failures, or side effects without repeating annotations or implementation.
- C++: concise Doxygen blocks (
-
Level 3 — function phases
- Upper group, optional for nested phases: C++
/* ===== Short Title ===== */; Python# ===== Short Title =====. - Common stage, preferred default: C++
/* ----- Short Title ----- */; Python# ----- Short Title -----. - Use short noun phrases and mark all sibling stages needed to reveal the structure. Do not use phase headings for individual objects or local operations.
- Upper group, optional for nested phases: C++
-
Level 4 — block descriptions
- C++: ordinary
/* ... */; Python: ordinary# .... - Describe an object, relationship, or non-obvious logic within one stage when a local comment is too weak.
- C++: ordinary
-
Level 5 — local details
- C++:
//; Python:#. - Use for subordinate implementation notes; keep end-of-line comments short.
- C++:
Skill Proposals
- Notice recurring repository-specific workflows that may warrant a Codex skill, but do not create or substantially update one without explicit approval.
- Before requesting approval, explain its use cases, purpose, scope, triggers, layout, supporting files, and validation.
- After approval, follow the official Codex skill-creation workflow and place repository-specific skills under
.agents/skills/, and validate the result. - Keep one-off facts and general rules in documentation, tests, or
AGENTS.mdinstead.
Safety Notes
- Do not revert user changes unless explicitly requested.
- Generated build outputs and rendered images should stay out of source control.
- Before large refactors, first confirm the intended directory layout and migration order with the user.
