Imported from project-chip/connectedhomeip (AGENTS.md). Install upstream with npx skills add project-chip/connectedhomeip. Copyright stays with the author.

AI Agent Guidelines for Matter SDK

This file provides guidelines and instructions for AI agents working on the Matter SDK codebase.

General Principles

• When in Rome: Match the prevailing style of the code being modified. See docs/style/CODING_STYLE_GUIDE.md.
• Atomicity: Make small, incremental changes. Do not mix refactoring with feature implementation.
• No Filler Names: Avoid names like "support", "common", "helpers", "util", "core". Use concrete names.
• Error Handling: Use CHIP_ERROR as the standard return type for fallible operations. Prefer VerifyOrReturnError and ReturnErrorOnFailure macros for concise error checking and propagation.
• Ensure resources are cleaned up appropriately, especially on early returns. Generally prefer RAII patterns for cleanup.
• Logging: Use the ChipLog* macros (e.g., ChipLogProgress, ChipLogError, ChipLogDetail) for logging. Ensure logs are appropriately categorized by module (e.g., AppServer, InteractionModel).

Ignored Directories

When searching for files or code patterns, ignore the following directories unless explicitly asked to look there:

• third_party/ (contains external dependencies)
• out/ (contains build artifacts)

Code Review Instructions

• Do not comment on content for XML files or .matter content for clusters.
• The SDK implements an in-progress Matter specification that may be in flux and may not be available to all contributors. Assume the Matter specification is unknown and out of scope unless you have explicit access to the latest version (e.g., via a specialized tool or skill).
• Avoid "pat on the back" style comments that just restate what the code is doing. Focus on suggesting concrete code improvements.
• Be concise. Do not over-explain code.
• Look for common typos and suggest fixes.
• Do not comment on whitespace or formatting (auto-formatters handle this).
• Review changes for embedded development:
  • Minimize use of heap allocation.
  • Optimize for resource usage (RAM/Flash).
  • Be cautious with complex templates that could lead to code bloat.

API Stability

Public APIs often have consumers outside this tree, so source compatibility is something to think about when changing or extending them. Breaking compatibility is not strictly prohibited, but should only be done for good reasons. There is no hard line between public and internal APIs: how much compatibility matters in a given area depends on how likely it is to be used by external clients, and on whether the API itself is considered stable or belongs to a feature still in development.

Where compatibility shapes a decision, record it in a comment or the commit message; a deliberate break and a deliberate workaround both read as accidents otherwise.

API preferences

• Prefer using chip::Span from src/lib/support/Span.h to pointer + size groups. Pass Span by value rather than const reference (treat it as a string_view)
• Use "foo"_span (i.e. operator _span) for const char spans instead of fromCharString.
• Prefer std::optional to chip::Optional
• Prefer StringBuilder from src/lib/support/StringBuilder.h to using snprintf for string formatting.

Coding Style (Highlights)

Refer to docs/style/CODING_STYLE_GUIDE.md for full details.

• C++: C++17 standard.
  • Use fixed-width integer types from <cstdint> for POD integer types
  • Avoid top-level using namespace in headers.
  • Use anonymous namespaces for file-internal classes/objects.
  • Avoid heap allocation and auto-resizing containers in core SDK.
• Python: Python 3.11 standard.
  • Use type hints on public APIs.
  • Include docstrings for public APIs.
• Always include {} bracketing for control flows, even if using one liners (e.g. for if, while, for and such)

Testing

• Unit tests are required for all changes unless unit testing is impossible (e.g., platform-specific code).
• Tests in src/python_testing and src/app/tests/suites which verify expected failures should clearly indicate why the failure is expected. Include a summary of the relevant specification requirements if possible.

Architectural Constraints

Code-Driven Clusters

Code-driven clusters are implementations in src/app/clusters that use DefaultServerCluster as a base class. When developing them:

• ReadAttribute, WriteAttribute, and InvokeCommand are by API contract only called for existent paths. Do not add path validity checks — they increase code size and are redundant as long as Attributes or AcceptedCommands are correct.
• Ember APIs and generated ZAP accessors must not be used outside the CodegenIntegration layer. CodegenIntegration.h/cpp is the documented bridge between generated configuration and code-driven cluster logic. Avoid types like EmberAfStatus or functions like emberAfContainsServer, emberAfReadAttribute, or emberAfWriteAttribute in core cluster code.
• When adding files: codegen-specific files belong in app_config_dependent_sources.cmake/gni; all others belong in BUILD.gn. Ensure every file (especially headers) is listed in one of these — there should be no unreferenced files.

Example Applications (Documentation Discovery)

When operating on or analyzing reference applications (such as examples/all-devices-app or custom simulator tools), always inspect that application's dedicated docs/ folder or ARCHITECTURE.md file to understand its dynamic runtime Interaction Model, specific CLI parameters, and recommended product baseline patterns before modifying or generating code.

Common Commands

Most commands require an activated environment. The user may or may not have already done that before running an agent harness; if $PW_PROJECT_ROOT is set the environment is probably active.

Environment Activation

You can run commands within the environment using scripts/run_in_build_env.sh: scripts/run_in_build_env.sh "command"

Alternatively, you can activate the environment in your shell: source scripts/activate.sh

Build and Test

• List available targets: scripts/run_in_build_env.sh "./scripts/build/build_examples.py targets"

• Generate Ninja files: scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet gen"

• Build and run all tests: scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-tests-clang --quiet build"

• Run a specific test: scripts/run_in_build_env.sh "ninja -C out/linux-x64-tests-clang --quiet path/to/test:test_name.run"

  • Explicit example: scripts/run_in_build_env.sh "ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster.run"

  • Compile and run can be separated (e.g. if running under some memory debugger or needing to set other options):

    ```bash
    scripts/run_in_build_env.sh "ninja -C out/linux-x64-tests-clang src/app/clusters/occupancy-sensor-server/tests:TestOccupancySensingCluster"`
    ./out/linux-x64-tests-clang/tests/TestOccupancySensingCluster
    ```
    

Building Common Apps

• chip-tool (Interactive commissioning tool): scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-chip-tool-clang --quiet build"
• all-clusters-app (Feature-rich device simulator): scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-all-clusters-clang --quiet build"
• all-devices-app (Alternative feature-rich simulator): scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target linux-x64-all-devices-clang --quiet build"

Development Resources

• docs/guides/writing_clusters.md
• docs/guides/migrating_ember_cluster_to_code_driven.md
• docs/testing/unit_testing.md
• docs/testing/integration_tests.md