Skip to content

Add AGENTS.md file - #4162

Merged
ahojnnes merged 3 commits into
mainfrom
user/jsch/agends-md
Mar 2, 2026
Merged

ahojnnes merged 3 commits into
mainfrom
user/jsch/agends-md

Conversation

@ahojnnes

@ahojnnes ahojnnes commented Mar 1, 2026 •

Copy link
Copy Markdown
Contributor

Iterated together with Claude on this to provide context for coding agents to get started in new sessions. This is supposedly the standard way to provide context for various AI tools (Claude, Gemini, Codex, ...).

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new documentation file, AGENTS.md, which serves as a detailed guide for AI coding agents interacting with the COLMAP project. It aims to streamline the onboarding process for automated tools by providing a structured overview of the codebase, its components, and operational procedures. Additionally, minor adjustments were made to the .gitignore file to improve build artifact exclusion and Python version management.

Highlights

  • New AGENTS.md file: A new AGENTS.md file has been added to provide comprehensive context for coding agents, detailing the project's overview, architecture, build instructions, and more.
  • .gitignore updates: The .gitignore file was updated to include .python-version for Python environment management and to generalize the ignored installation directories from install-debug/ and install-release/ to a single install*/ entry.
Changelog
  • .gitignore
    • Added .python-version to ignore local Python version files.
    • Generalized install-debug/ and install-release/ to install*/ for broader exclusion of build output directories.
  • AGENTS.md
    • Added a new Markdown file providing a comprehensive guide for coding agents.
    • Included sections on project overview, directory structure, module dependency layers, key classes and files, build instructions, testing procedures, code style conventions, and external dependencies.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new AGENTS.md file, which serves as a comprehensive guide to the COLMAP codebase, primarily for AI agents. It also includes minor improvements to the .gitignore file. The new documentation is well-structured and detailed. I've provided a couple of suggestions to improve the accuracy of the build instructions and the module dependency hierarchy described in AGENTS.md.

Comment thread AGENTS.md Resolved
Comment thread AGENTS.md Resolved

@lpanaf lpanaf left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@ahojnnes
ahojnnes merged commit 5580004 into main Mar 2, 2026
14 checks passed
@ahojnnes
ahojnnes deleted the user/jsch/agends-md branch March 2, 2026 09:58
sarlinpe added a commit that referenced this pull request Nov 3, 2026
## Summary

Adds a reusable [Agent Skill](https://agentskills.io)
(`.agents/skills/colmap-review/SKILL.md`) that instructs coding agents
(Codex, Gemini CLI, Cursor, Claude Code, etc.) to perform
maintainer-grade code reviews on COLMAP changes — uncommitted diffs,
commits/branches, or GitHub PRs — without modifying code.

This complements `AGENTS.md` (#4162): agents load only the short
frontmatter description by default and pull in the full review
instructions on demand (e.g. `"review this"` or `"review my PR"`), and
`AGENTS.md` links to it for harnesses without native skill discovery,
keeping regular coding sessions lean.

### What it covers
- **Modularity, readability & diff size:** Prefers short, cohesive
functions with self-documenting names and tightly scoped (`const`)
variables over long functions with wide scopes or opaque blocks, checks
whether sub-steps can be extracted into helpers or already exist in
COLMAP (`math/`, `geometry/`, `sensor/`, `scene/`, `estimators/`),
removes dead code and speculative options, and pushes scattered
`if/else` plumbing behind existing domain abstractions (`Camera`, `Rig`,
`Frame`, `TwoViewGeometry`).
- **Geometric, numerical & SfM/MVS correctness:**
Non-perspective/fisheye/spherical camera rays (`CamRayFromImg` vs.
`CamFromImg`), pixel-center (`+0.5`) vs. integer-grid coordinate
conventions, panoramic seam wrap-around, solver
conditioning/degeneracies (including on the final RANSAC inlier set) and
convergence/`allFinite()` checks, RANSAC vs. Ceres outlier/cheirality
residual semantics, missing Ceres manifolds (`EigenQuaternionManifold`,
`SphereManifold`), `target_from_source` frame and `Rig` composition, and
`FlatHashMap` iteration nondeterminism.
- **Safety, `pycolmap` & CI portability:** Precondition checks before
mutating `Reconstruction`/`Database`, clean exception propagation
(`THROW_CHECK*`) over `LOG(FATAL)` in library/worker code, schema/format
backwards compatibility, `pycolmap` container lifetime/GIL/STL
copy-conversion/`None`/option-parity hazards, and
feature-gate/CUDA/HIP/headless/Windows/formatting portability.
- **Performance & empirical evidence:** `O(N^2)` patterns, hot-loop
copies/allocations, and requiring benchmark justification (e.g. ETH3D or
multi-seed synthetic sweeps) for algorithmic or default-parameter
changes.
- **Tests & conventions:** Focused C++ regression tests (`*_test.cc`)
over bloated `pycolmap` pipeline tests, catching vacuous assertions,
reusing COLMAP matchers (`ReconstructionEq`, `Rigid3dNear`,
`SynthesizeDataset`, in-memory SQLite), and checking concrete repo
conventions (`FlatHashMap`/`NodeHashMap`, strong IDs,
`target_from_source`, SPDX headers).
- **Actionable output contract:** Every finding must be verified against
connected callers in the repo and have either a concrete failure trigger
or a concrete simplification, grouped into `Must fix` / `Should fix` /
`Nit` with a diff-reduction summary and verdict.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants