Skip to content

AI_GUIDELINES.md

Latest commit

 

History

History
347 lines (267 loc) · 14.3 KB

AI_GUIDELINES.md

File metadata and controls

347 lines (267 loc) · 14.3 KB
Raw

AI Guidelines for Hyperledger Cacti

This document establishes advisory guidelines for the responsible use of artificial intelligence (AI) and large language model (LLM) tooling across all Hyperledger Cacti activities, including code contributions, reviews, documentation, security auditing, and CI/CD automation.

These guidelines complement the LF Decentralized Trust Code of Conduct, the project Code of Conduct, and the Apache-2.0 License under which Cacti is released.

1. Introduction

AI-assisted development is becoming ubiquitous in both proprietary and open-source software. LF Decentralized Trust projects can leverage these tools to promote better implementation cycles — from LLM-assisted code reviews and security audits to automated optimization and refactoring.

At the same time, threat actors are actively using LLMs to discover and exploit vulnerabilities at scale (see Napier University research on LLM-driven exploitation). Defenders must adopt the same tools proactively — using AI for vulnerability scanning, dependency analysis, and code review to bridge the gap.

The LF Decentralized Trust Code of Conduct provides a benchmark for self-evaluation and promotes high standards of professional practice. These AI guidelines extend that benchmark to AI-assisted workflows, ensuring that the use of generative tooling upholds the same values of transparency, accountability, and respect that govern all community interactions.

2. Guiding Principles

2.1 Individual Responsibility

AI-generated code is the sole responsibility of the committer. The contributor who submits a pull request is accountable for the correctness, security, licensing compliance, and long-term maintenance of all code in that PR — regardless of whether it was written by a human or generated by a tool. This mirrors the ASF Generative Tooling Guidance, which reminds contributors that they are responsible for disclosing any copyrighted materials in submitted contributions.

2.2 Disclosure

Code that was generated or assisted by AI — whether in implementation, review, documentation, testing, or any other activity associated with open-source contribution — shall be disclosed. Following the convention adopted by the Linux kernel and the ASF, contributions should include an Assisted-by tag in the commit message using the following template:

Assisted-by: PROVIDER:MODEL_VERSION [TOOL1] [TOOL2]

Where:

  • PROVIDER is the model provider in kebab-case (e.g., anthropic, openai, google).
  • MODEL_VERSION is the specific model version used (e.g., claude-opus-4-6, gpt-5.4).
  • [TOOL1] [TOOL2] are optional specialized analysis tools used during the contribution (e.g., eslint, semgrep, coccinelle).

Basic development tools (git, node, yarn, editors) should not be listed.

Examples:

Assisted-by: anthropic:claude-opus-4-6 eslint semgrep
Assisted-by: anthropic:claude-sonnet-4-6
Assisted-by: openai:gpt-5.4
Assisted-by: google:gemini-2.5-pro
Assisted-by: deepseek:deepseek-r1
Assisted-by: openai:o3
Assisted-by: anthropic:claude-sonnet-4-5
Assisted-by: anthropic:claude-opus-4-5
Assisted-by: openai:gpt-5.4-mini
Assisted-by: openai:gpt-5.3-codex

This structured format allows future tooling to extract AI provenance information into machine-parsable records and enables tracking the evolving role of AI in the development process.

Providers and Model Versions

If your provider or model is not listed, use the provider's name in kebab-case and the official model identifier. When a model has a date suffix (e.g., claude-opus-4-5-20251101), the short alias (e.g., claude-opus-4-5) is acceptable. Always prefer the most specific version you can identify. These lists are not exhaustive.

Providers: anthropic, openai, google, xai, deepseek, mistral, meta, alibaba.

Models: claude-opus-4-6, claude-opus-4-5, claude-opus-4-1, claude-opus-4, claude-sonnet-4-6, claude-sonnet-4-5, claude-sonnet-4-1, claude-sonnet-4, claude-3-opus, claude-3.5-sonnet, claude-3.5-haiku, gpt-5.4-pro, gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.3, gpt-5.3-codex, gpt-4.1, gpt-4.1-mini, gpt-4o, o4-mini, o3, o3-mini, o1, gemini-3.1-pro, gemini-3.1-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash, grok-4, grok-3, grok-3-mini, deepseek-r1, deepseek-v3, mistral-large, codestral, llama-4, llama-3.3, qwen-3.5, qwen-3, qwen-2.5-coder.

2.3 Human Review

All AI-generated output must be reviewed by a human before submission. AI output does not constitute a code review. A PR that consists entirely of unreviewed AI-generated code does not meet the project's review standards as defined in CONTRIBUTING.md and GOVERNANCE.md.

2.4 Understanding Your Own Code

Contributors must understand every line of code they submit, regardless of whether it was written by hand or generated by AI. If you cannot explain what the code does and why, do not submit it. Reviewers may ask you to explain any part of your change, and you are expected to answer from your own understanding.

When responding to review comments, you must do so without relying on AI tools. Reviewers want to engage directly with you, not with generated responses. If you do not engage directly with reviewers, the PR will be closed.

2.5 Compliance with Project Standards

AI-assisted contributions are held to the same standards as human-authored contributions. All code, documentation, and other artifacts produced with AI assistance must adhere to:

  • Code of Conduct — all interactions and contributions must follow the LF Decentralized Trust and project Codes of Conduct.
  • CONVENTIONS.md — naming, style, structure, and architectural conventions for the Cacti monorepo.
  • CONTRIBUTING.md — contribution workflow, PR requirements, DCO sign-off, and review process.

AI tooling does not exempt a contributor from any of these policies. In particular, AI-assisted PRs must follow the project's Small, Focused Pull Requests principle — one logical change per PR, small diffs, and self-contained commits. AI tooling can easily produce large changes, thus contributors must break work into focused, reviewable units. Prefer multiple small PRs to one big all-encompassing one.

Reviewers should verify that AI-generated code meets the same bar as manually written code, and reject contributions that introduce convention violations, AI slop (unnecessary restating comments, over-engineered abstractions, hallucinated APIs), or deviations from established patterns.

3. Scope of Applicability

These guidelines apply to all contributions to Hyperledger Cacti, including but not limited to:

  • Source code (TypeScript, Solidity, Go, etc.)
  • Documentation and README files
  • Code reviews and PR comments
  • Test suites and test data
  • CI/CD pipeline configurations
  • Images, diagrams, and visual assets
  • Translations and localization

Exemptions

The following activities do not require disclosure:

  • Grammar and spelling corrections made by IDE or editor features
  • Single-line IDE autocomplete suggestions (e.g., tab-completion of a variable name or method signature)
  • Standard code formatting applied by tools like Prettier or ESLint

4. Licensing & Intellectual Property

Contributors using AI tools must ensure that:

  1. Tool terms of service do not place restrictions on the output that would be inconsistent with the Open Source Definition or the Apache-2.0 license.

  2. No third-party copyrighted material is included in the output without appropriate licensing, or reasonable certainty that the output is not copyrightable subject matter. Contributors should prefer tools that identify content similar to training data and disclose the license of that content.

  3. No proprietary or confidential code should be used as input to AI tools that may store, log, or use prompts for training, unless the tool's data handling policy explicitly permits it.

For detailed treatment of third-party materials in Apache projects, see the ASF's 3rd Party Licensing Policy and 3rd Party Works guidance.

5. AI-Assisted Security Auditing (Defensive AI)

Threat actors are using LLMs to automate vulnerability discovery and exploit generation. Open-source projects must use the same tools defensively. Cacti encourages the use of AI for:

  • Vulnerability scanning: Using LLMs or AI-powered static analysis to identify common vulnerability patterns (OWASP Top 10, CWE Top 25) in source code.
  • Dependency analysis: AI-assisted review of dependency trees for known vulnerabilities, license conflicts, or supply-chain risks.
  • Code review augmentation: Using AI to flag potential security issues during PR review — as a supplement to, never a replacement for, human review.
  • Fuzz testing: AI-guided fuzzing to discover edge cases and unexpected input handling.
  • Incident response: Using AI to accelerate triage and root-cause analysis of reported security issues.

Requirements

  • All AI-detected security findings must be verified by a human before being acted upon or disclosed.
  • AI tools used for security auditing should be documented in the relevant PR or issue.
  • For reporting security vulnerabilities, follow the process described in SECURITY.md.

6. Recommended Practices

  1. Use tools that provide training-data attribution — prefer tools that can identify when output is similar to training data and disclose the source license.

  2. Prefer open-source-compatible terms of service — verify that the AI tool's ToS does not restrict open-source use of generated output.

  3. Include provenance in commits — use the structured Assisted-by: PROVIDER:MODEL_VERSION [TOOL1] [TOOL2] tag in commit messages when AI-generated content is substantial (see §2.2 for the full template).

  4. Review all output — check AI-generated code for correctness, security vulnerabilities, licensing issues, and adherence to project style (see CONVENTIONS.md).

  5. Be skeptical of AI confidence — LLMs can produce plausible but incorrect output. Treat AI suggestions as a starting point, not a final answer.

  6. Document prompts for non-trivial generations — when AI is used to generate significant architectural decisions or complex algorithms, consider documenting the prompt and reasoning in the PR description.

7. What AI Cannot Do

  • AI cannot be listed as an author or contributor. Credit belongs to the humans who prompted, reviewed, and submitted the work.

  • AI cannot approve pull requests. PR approval requires a human maintainer as defined in GOVERNANCE.md.

  • AI agents must not add Signed-off-by or DCO tags. Only humans can legally certify the Developer Certificate of Origin. The human submitter is responsible for reviewing all AI-generated code, ensuring compliance with licensing requirements, adding their own Signed-off-by tag to certify the DCO, and taking full responsibility for the contribution. This aligns with the Linux kernel policy on AI and the DCO.

  • AI cannot make governance decisions. Decisions about project direction, releases, and maintainer status are made by humans per the project's governance model.

  • AI output is not a substitute for a code review. Even if AI tools flag or approve code, the project's review requirements (at least two maintainer reviews) still apply.

8. Evolving Guidelines

This is a rapidly evolving area. As AI technology, legal frameworks, and community norms continue to develop, these guidelines will be reviewed and updated periodically. We encourage community feedback through:

Changes to these guidelines follow the same PR and review process as any other project documentation.

9. References

This document was drafted with the assistance of GitHub Copilot (Claude Opus 4.6 agent mode). The content was reviewed, edited, and approved by the Hyperledger Cacti team. In keeping with the disclosure principle in §2.2, this notice is provided for transparency.