[LTP] [PATCH v2] Add agents configuration for code reviews
Andrea Cervesato
andrea.cervesato@suse.de
Mon Feb 16 20:11:17 CET 2026
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add agents configuration generated from the LTP documentation using
Claude Code. The agents/ folder has been added in order to split agents
configuration from the actual documentation and it's pointed via
AGENTS.md file in the root folder. This is enough to use OpenCode in the
main LTP root folder and to start reviewing LTP code.
The code reviews (obviously) differ between models, so it's really hard
to say what model should be used and what not. But, for sure, Claude Code
provides great features at a really high price. For this reason, it's
worth to mention that the reviewiers job should be done both by
developers, before sending patches, and by reviewers, in a second
moment.
Realy important, we should probably find an open source model alternative
that is "good enough" for our purpose.
NOTE: at the moment, agents/ and doc/ folders are overlapping
information, so we might start to think how to create an AGENTS.md that
directly points to a re-structured doc/ folder, simplified enough so
agents can use it as a reference, instead of having a double folder.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
Changes in v2:
- rewrite the entire agents/ structure to reduce the LLM allucination
and to focus on reviews only
- AGENTS.md now is defining basic project usage and it points to the
agents/review.md for review requests
- Link to v1: https://lore.kernel.org/r/20260216-agents_file-v1-1-53ec6a8ecf32@suse.com
---
AGENTS.md | 99 ++++++++++++++++++++++++++++++++++++++++
agents/c-tests.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++
agents/ground-rules.md | 71 +++++++++++++++++++++++++++++
agents/review.md | 50 ++++++++++++++++++++
agents/shell-tests.md | 95 ++++++++++++++++++++++++++++++++++++++
5 files changed, 436 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..634c0d9812c9c80297e35563870b0f350a9b5a91
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,99 @@
+# Linux Test Project (LTP)
+
+LTP delivers tests to the open source community that validate the
+reliability, robustness, and stability of the Linux kernel and related
+features. Tests are written in C or portable POSIX shell. The project uses
+GNU Autotools for its build system and follows the Linux kernel coding style.
+
+**License**: GPL-2.0-or-later (`SPDX-License-Identifier: GPL-2.0-or-later`)
+
+## Technology Stack
+
+- **Languages**: C (primary), portable POSIX shell
+- **Build system**: GNU Autotools (autoconf, automake, make)
+- **Compiler**: gcc (clang also supported in CI)
+- **Coding style**: Linux kernel coding style
+- **Test runner**: kirk (replacing legacy `runltp`)
+- **Documentation**: reStructuredText + Sphinx
+
+## Project Structure
+
+- `testcases/` - All test binaries (C and shell)
+ - `testcases/kernel/syscalls/` - Syscall and libc wrapper tests
+ - `testcases/open_posix_testsuite/` - Open POSIX testsuite fork
+ - `testcases/lib/` - Shell test library and shell loader
+- `include/` - LTP library headers (`tst_test.h` is the main API)
+ - `include/lapi/` - Fallback kernel API definitions for older systems
+ - `include/mk/` - Build system include files
+- `lib/` - LTP C library source (`tst_*.c` files)
+ - `lib/newlib_tests/` - LTP library self-tests
+- `runtest/` - Runtest files defining test suites (e.g. `syscalls`, `mm`)
+- `scenario_groups/` - Default sets of runtest files
+- `doc/` - Sphinx documentation (RST format)
+- `infrastructure/` - Terraform configs (if present)
+- `scripts/` - Helper scripts
+- `ci/` - CI dependency installation scripts
+- `.github/workflows/` - GitHub Actions CI workflows
+- `tools/` - Release and maintenance tools
+- `agents/` - AI Agents configurations
+
+## Environment Setup
+
+### Prerequisites
+
+- git
+- autoconf, automake, m4
+- make
+- gcc
+- pkgconf / pkg-config
+- libc headers
+- linux headers
+
+### Download Source
+
+```sh
+git clone --recurse-submodules https://github.com/linux-test-project/ltp.git
+cd ltp
+```
+
+### Build from Source
+
+```sh
+make autotools
+./configure
+make
+```
+
+### Install (default prefix: /opt/ltp)
+
+```sh
+make install
+```
+
+### Rebuild from Scratch (required after build system changes)
+
+```sh
+make autotools
+./configure
+make
+```
+
+## FILE LOADING INSTRUCTIONS
+
+### Code review (ALWAYS LOAD WHEN PATCH REVIEW IS REQUESTED)
+
+- `agents/review.md` - Entry point for the review agent
+
+## Additional Resources
+
+- Documentation: https://linux-test-project.readthedocs.io/
+- Source code: https://github.com/linux-test-project/ltp
+- Mailing list: https://lore.kernel.org/ltp/
+- Patchwork: https://patchwork.ozlabs.org/project/ltp/list/
+- Kirk (test runner): https://github.com/linux-test-project/kirk
+- Linux kernel coding style: https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+For detailed API reference, see `doc/developers/api_c_tests.rst` and
+`doc/developers/api_shell_tests.rst`.
+For build system details, see `doc/developers/build_system.rst`.
+For test writing tutorial, see `doc/developers/test_case_tutorial.rst`.
diff --git a/agents/c-tests.md b/agents/c-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..dd966ec723d5182eff422339174e01e4dab66983
--- /dev/null
+++ b/agents/c-tests.md
@@ -0,0 +1,121 @@
+# C Tests
+
+## Test Structure
+
+```c
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * Copyright (c) YYYY Your Name <email>
+ */
+
+/*\
+ * High-level RST-formatted test description goes here.
+ * Explain _what_ is being tested (exported to docs).
+ *
+ * The following part is OPTIONAL:
+ * [Algorithm]
+ *
+ * Explaination of how algorithm in the test works in a list (-) syntax.
+ */
+
+#include "tst_test.h"
+
+static void run(void)
+{
+ tst_res(TPASS, "Test passed");
+}
+
+static struct tst_test test = {
+ .test_all = run,
+};
+```
+
+## Mandatory Tests Rules
+
+- Follow Linux kernel coding style
+- Include `tst_test.h` as the main API header
+- `main()` is provided by the test library; do not define it, unless
+ `TST_NO_DEFAULT_MAIN` is used inside the test
+- Use `struct tst_test` to configure test callbacks, requirements, and metadata
+- Use `tst_res()` for reporting (TPASS, TFAIL, TCONF, TBROK, TINFO)
+- Use `tst_brk()` for fatal errors that abort the test
+- Use `SAFE_*` macros for system calls that must not fail
+- Use `TEST()` macro to capture return value in `TST_RET` and errno in `TST_ERR`
+- Keep handlers thin; use `.setup` and `.cleanup` callbacks
+- Cleanup must run on all exit paths (unmount, restore sysctls, delete temp
+ files, kill processes)
+- Do not use the old API (`test.h`); use only the new API (`tst_test.h`)
+- Syscall tests go under `testcases/kernel/syscalls/`
+- Each test must have an entry in the appropriate `runtest/` file
+- New test binaries must be added to the corresponding `.gitignore`
+- Datafiles go in a `datafiles/` subdirectory, installed to
+ `testcases/data/$TCID`
+- Sub-executables use `$TESTNAME_` prefix
+- Use `.needs_tmpdir = 1` and work in the current directory for temp files
+- Use `.min_kver` for kernel version gating; prefer runtime checks over
+ compile-time checks
+- Return `TCONF` when a feature is unavailable (not `TFAIL`)
+- If a test is a regression test it should include `.tags` in the
+ `struct tst_test` definition
+
+## Code Pattern Examples
+
+### ✅ Good Code (New API)
+
+```c
+#include <stdlib.h>
+#include "tst_test.h"
+
+static int fd;
+
+static void setup(void)
+{
+ // SAFE macro aborts test if it fails
+ fd = SAFE_OPEN("test_file", O_RDWR | O_CREAT, 0644);
+}
+
+static void cleanup(void)
+{
+ if (fd > 0)
+ SAFE_CLOSE(fd);
+}
+
+static void run(void)
+{
+ if (write(fd, "a", 1) != 1) {
+ tst_res(TFAIL | TERRNO, "write() failed");
+ return;
+ }
+ tst_res(TPASS, "write() succeeded");
+}
+
+static struct tst_test test = {
+ .test_all = run,
+ .setup = setup,
+ .cleanup = cleanup,
+ .needs_tmpdir = 1,
+ .needs_root = 1,
+};
+
+```
+
+### ❌ Bad Code (Legacy/Unsafe)
+
+```c
+/* WRONG HEADER */
+#include <stdio.h>
+#include "test.h"
+
+int main(void) /* WRONG: NO MAIN ALLOWED */
+{
+ int fd = open("/tmp/file", O_RDWR); /* WRONG: UNSAFE & HARDCODED PATH */
+
+ if (fd < 0) {
+ perror("open"); /* WRONG: USE tst_res OR SAFE_MACRO */
+ exit(1);
+ }
+
+ tst_resm(TPASS, "test passed"); /* WRONG: OLD PRINT FUNCTION */
+ tst_exit();
+}
+```
diff --git a/agents/ground-rules.md b/agents/ground-rules.md
new file mode 100644
index 0000000000000000000000000000000000000000..b296ea8e2043568cb4a315a16a19d09f2ef774e1
--- /dev/null
+++ b/agents/ground-rules.md
@@ -0,0 +1,71 @@
+# Ground Rules
+
+These rules are **mandatory** and must never be violated when writing or
+modifying LTP code.
+
+## No kernel bug workarounds
+
+Never work around a known kernel bug in LTP test code. Workarounds mask
+failures for everyone else. If a test fails because a fix was not backported,
+that is the expected (correct) result.
+
+## No sleep-based synchronization
+
+Never use `sleep()` to synchronize between processes. It causes rare flaky
+failures, wastes CI time, and breaks under load. Use instead:
+
+- `waitpid()/SAFE_WAITPID()` — when parent just needs child to finish
+- `TST_CHECKPOINT_WAIT()` / `TST_CHECKPOINT_WAKE()` — when child must reach a
+ code point before parent continues (futex-based, shared memory)
+- `TST_PROCESS_STATE_WAIT()` — when child must be sleeping in a syscall
+ (polls `/proc/$PID/stat`)
+- Exponential-backoff polling loop — for async or deferred kernel actions
+
+## Runtime feature detection only
+
+Compile-time checks (`configure.ac`) may only enable fallback API definitions
+in `include/lapi/`. Never assume compile-time results reflect the running
+kernel. At runtime use: errno checks (`ENOSYS` / `EINVAL`), `.min_kver`,
+`.needs_kconfigs`, or kernel `.config` parsing.
+
+## Minimize root usage
+
+Do not require root unless the test truly needs it. If root is needed,
+document _why_ in the test's doc comment. Drop privileges for sections that
+do not need them.
+
+## Always clean up
+
+Every test must leave the system exactly as it found it, even on failure or
+early exit. Unmount filesystems, restore sysctls and `/proc`/`/sys` values,
+delete temp files/dirs, kill spawned processes, remove cgroups/namespaces,
+detach loop devices, restore ulimits. Prefer library helpers:
+`.needs_tmpdir`, `.save_restore`, `.needs_device`, `.restore_wallclock`,
+`.needs_cgroup_ctrls`.
+
+## Write portable code
+
+- No nonstandard libc APIs when a portable equivalent exists
+- No assumptions about 64-bit, page size, endianness, or tool versions
+- Architecture-specific tests must still compile everywhere; gate with
+ `.supported_archs`
+- Shell tests must be portable POSIX shell (no bash-isms); verify with
+ `make check`
+
+## One logical change per patch
+
+Split work into small, well-defined patches. Each patch must:
+
+- compile successfully on its own
+- keep all tests and tooling functional
+- not introduce intermediate breakage
+- have a clear commit message explaining the change
+ Patches mixing unrelated changes will be delayed or ignored.
+
+## Unreleased kernel features
+
+Tests for features not yet in a mainline kernel release use the `[STAGING]`
+subject prefix and go into `runtest/staging` only. They will not be merged
+into default test suites until the kernel code is finalized and released.
+That's the raw markdown, ready to copy into an AGENTS.md or any agent
+configuration file.
diff --git a/agents/review.md b/agents/review.md
new file mode 100644
index 0000000000000000000000000000000000000000..ac7cb494bc345ad354d24b66bf9112a8caaecd71
--- /dev/null
+++ b/agents/review.md
@@ -0,0 +1,50 @@
+# LTP Patch Review Protocol
+
+You are an agent that performs a deep regression analysis on patches for the
+LTP - Linux Test Project.
+
+The review must be requested for one of the following:
+
+- Git commit
+- Git branch
+- Multiple git commits
+- URL to patchwork
+- URL to lore
+- Local patches file
+
+## Core Files (ALWAYS LOAD FIRST)
+
+1. `ground-rules.md` - Consolidate the rules for LTP tests
+
+## Review Git Commit
+
+- Commits must include `Signed-off-by:` tag
+- Commit messages must be clear, following kernel commit style
+- Use `[STAGING]` subject prefix for tests targeting unreleased kernel features
+- `Fixes: hash` if it fixes particular LTP commit
+- `Fixes: #N` if it fixes github issue number N, so it's automatically closed
+
+## Review C Tests
+
+- Always load `c-tests.md` before starting the review and make sure that tests
+ follow all the rules
+- Compare syscall usage with man pages and kernel code
+
+### C Tests Contribution Checklist (ALL MUST PASS)
+
+- Patches apply cleanly over latest git
+- Test compiles and runs fine (check with `-i 10` and `-i 0` too)
+- Runtest entries are in place
+- New test binaries are added to corresponding `.gitignore` files
+- Run `make check` or `make check-$TCID` in the test directory (uses vendored
+ `checkpatch.pl` from kernel tree)
+
+## Review Shell Tests
+
+Always load `c-tests.md` before starting the review.
+
+### Shell Tests Contribution Checklist (ALL MUST PASS)
+
+- Patches apply cleanly over latest git
+- Make sure that shell tests rules are applied
+- `make check` emits no warnings for your test
diff --git a/agents/shell-tests.md b/agents/shell-tests.md
new file mode 100644
index 0000000000000000000000000000000000000000..0a93b54bddec9531e9a17291b5b8c2a9e525a540
--- /dev/null
+++ b/agents/shell-tests.md
@@ -0,0 +1,95 @@
+# Shell Test API
+
+## Mandatory file structure
+
+Every shell test must follow this exact layout, in order. Omitting or
+reordering these blocks will break the shell loader.
+
+```sh
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) YYYY Author Name <email@example.org>
+# ---
+# doc
+# Brief RST description of what the test verifies.
+#
+# Additional detail if needed (exported to generated docs).
+# ---
+# ---
+# env
+# {
+# "needs_root": true,
+# "needs_tmpdir": true
+# }
+# ---
+
+TST_SETUP=setup
+TST_CLEANUP=cleanup
+
+. tst_loader.sh
+
+setup()
+{
+ tst_res TINFO "setup executed"
+}
+
+cleanup()
+{
+ tst_res TINFO "cleanup executed"
+}
+
+tst_test()
+{
+ tst_res TPASS "Test passed"
+}
+
+. tst_run.sh
+```
+
+## Block-by-block rules
+
+1. **Shebang + license + copyright** — always `#!/bin/sh`, always
+ `GPL-2.0-or-later`.
+2. **`# --- doc`** block — RST-formatted comment describing _what_ is tested.
+ Parsed and exported to the online test catalog. Must be present.
+3. **`# --- env`** block — JSON serialization of `struct tst_test` fields.
+ Must be present even when empty (`{}`). Keys map nearly 1:1 to the C
+ struct (e.g. `"needs_root": true`, `"needs_tmpdir": true`,
+ `"needs_kconfigs": ["CONFIG_NUMA=y"]`, `"tags": {["linux-git", "<hash>"]}`).
+4. **`TST_SETUP` / `TST_CLEANUP` variables** — set _before_ sourcing
+ `tst_loader.sh`. Optional. Setup runs once before tests; cleanup runs
+ once after tests or on `tst_brk` interruption.
+5. **`. tst_loader.sh`** — sources the shell loader, which internally
+ launches `tst_run_shell.c` to parse the env block and initialize the C
+ test library. Must come after variable assignments and before function
+ definitions.
+6. **`setup()` / `cleanup()` functions** — defined after the loader is
+ sourced. Names must match the variables set above.
+7. **`tst_test()` function** — the actual test logic. Report results with
+ `tst_res` and `tst_brk`. Results are stored in shared memory so child
+ processes do not need to propagate them.
+8. **`. tst_run.sh`** — must be the very last line. Triggers test execution.
+
+## Shell coding style
+
+- **Portable POSIX shell only** — no bash-isms (no `[[ ]]`, no arrays,
+ no `function` keyword, no process substitution)
+- Allowed exceptions: `local` keyword inside functions, `-o` and `-a` test
+ operators
+- Code must support also `dash`
+- Keep lines under 80 characters
+- Use tabs for indentation
+- Quote all variable expansions
+- Avoid unnecessary subshells
+- Do not name functions after common shell commands
+
+## Running shell tests from the source tree
+
+```sh
+# From the test's directory (depth may vary)
+PATH=$PATH:$PWD:$PWD/../../lib/ ./foo01.sh
+```
+
+The `../../lib/` path must point to `testcases/lib/` where `tst_loader.sh`,
+`tst_run.sh`, and the compiled `tst_run_shell` binary reside. Adjust the
+number of `../` segments to match the test's depth relative to `testcases/`.
---
base-commit: ef0d9ed8b19b9e32dc9ee6c0a3b14983bc387fd1
change-id: 20260215-agents_file-344bdc3300d0
Best regards,
--
Andrea Cervesato <andrea.cervesato@suse.com>
More information about the ltp
mailing list