Guidance for coding agents

This file is for AI coding agents (Claude Code, Cursor, Codex, Copilot, ...) working in this repository. Humans should read CONTRIBUTING.md.

Primary sources

Official documentation: https://docs.fluentd.org/
- Index for agents: https://docs.fluentd.org/llms.txt
- Every page is also available as Markdown by appending .md to its URL, e.g. https://docs.fluentd.org/configuration/config-file.md
Read the documentation before answering questions about configuration syntax or plugin parameters. Do not invent parameters; check the plugin's page or its config_param declarations in this repository.
Configuration has two formats.
- Classic: https://docs.fluentd.org/configuration/config-file.md
- YAML: https://docs.fluentd.org/configuration/config-file-yaml.md

lib/fluent/plugin/ – bundled plugins (in_*.rb, out_*.rb, filter_*.rb, parser_*.rb, formatter_*.rb, buf_*.rb, storage_*.rb, sd_*.rb, metrics_*.rb)
lib/fluent/plugin_helper/ – plugin helpers
lib/fluent/config/ – configuration parsers (classic and YAML)
test/ – tests written with test-unit
templates/new_gem/ – files generated by fluent-plugin-generate

Install: bundle install
Run all tests: bundle exec rake test
Run one file: bundle exec ruby -Ilib -Itest test/plugin/test_in_tail.rb
Plugin API reference: https://docs.fluentd.org/plugin-development/README.md
Plugin helper reference: https://docs.fluentd.org/plugin-helper-overview/README.md
Test helpers for plugins: https://docs.fluentd.org/plugin-development/plugin-test-code.md

Follow CONTRIBUTING.md. Commits need a DCO sign-off (git commit -s).
Keep changes minimal and focused; do not reformat unrelated code.
Add or update tests under test/ for behavior changes.
Do not add runtime dependencies without discussion.
Match the surrounding code style; there is no autoformatter to run. CI runs rubocop, but only the Security and Performance cops are enabled.
Fluentd runs on Linux, macOS and Windows. CI tests ubuntu-latest, macos-latest, windows-latest and windows-11-arm. Assume your change must work on Windows.

Pull requests follow .github/PULL_REQUEST_TEMPLATE.md. Keep its headings, including Docs Changes and Release Note, and write Fixes #<n> when an issue exists.
Blank issues are disabled. Use .github/ISSUE_TEMPLATE/bug_report.yml or .github/ISSUE_TEMPLATE/feature_request.yml and answer every required field.
Questions belong in Discussions, not in issues.
Note that gh pr create --body and gh issue create --body skip the template. Pass --template, or reproduce the template's sections in the body you supply.