-
Notifications
You must be signed in to change notification settings - Fork 20
docs: add AI-Assisted Development Policy #26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
eranco74
wants to merge
3
commits into
osac-project:main
Choose a base branch
from
eranco74:main
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # AI workflow artifacts | ||
| .planning/ | ||
| *.gsd |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,137 @@ | ||
| # AI-Assisted Development Policy for OSAC | ||
|
|
||
| ## Purpose | ||
|
|
||
| The software industry is transitioning to an Agentic Software Development Lifecycle (SDLC), where autonomous agents working alongside humans - plan, code, test, and deploy software. As a modern open-source platform, OSAC is uniquely positioned to set the standard for this era by aggressively adopting AI to accelerate development and eliminate the technical and knowledge debt that often plagues long-term projects. | ||
| Given that OSAC is designed for deployment in highly sensitive environments, including sovereign clouds and medical applications, we recognize our responsibility to ensure AI is adopted with rigor. Our goal is not merely to maintain existing standards, but to measurably improve code quality, safeguard open-source integrity, and foster an inclusive, human-centric contributor community. | ||
| This (evolving) document establishes the policy for how all contributors, whether Red Hat employees or external community members, utilize AI coding tools (Claude Code, GitHub Copilot, Cursor, Gemini, etc.) and provides pointers to the best practices our engineers are adopting today. | ||
|
|
||
| ## Guiding Principles | ||
|
|
||
| 1. **Human accountability is non-negotiable.** Every contribution has a human owner who understands, can explain, and takes responsibility for the code - regardless of how it was produced. | ||
|
|
||
| 2. **No contributor is blocked.** AI tools are encouraged but never required. Contributors without access to Claude, Jira, or other Red Hat-internal tooling can participate fully through standard open-source workflows (GitHub issues, PRs, mailing lists). As our AI SDLC matures, we will revisit this principle to ensure it balances inclusivity with our ability to adopt the most effective workflows. | ||
|
|
||
| 3. **Validation is deterministic.** No matter how far we push AI integration, one boundary remains non-negotiable: builds, tests, and CI checks must be reproducible without AI tools. This ensures we move fast without losing trust. AI helps produce code and reviews, but deterministic tests verify correctness - fundamentally different activities with distinct reliability requirements. | ||
|
|
||
|
|
||
| 4. **Transparency builds trust.** AI usage in contributions should be disclosed. This is not a gatekeeping mechanism - it helps reviewers calibrate their review and builds community norms. | ||
|
|
||
| 5. **Quality over velocity.** AI tools should help us build better software faster, not generate more code faster. The goal is higher-quality contributions, not higher volume. | ||
|
|
||
| 6. **Tool-agnostic by design.** Project workflows and documentation should not lock contributors into a specific AI tool. We aim to adopt cross-tool standards (such as AGENTS.md) as they mature, and ensure that tool-specific configuration files (CLAUDE.md, .cursorrules, etc.) serve as useful developer documentation for all contributors. | ||
|
|
||
| ## Contributor Access & Inclusivity | ||
|
|
||
| ### How we keep OSAC accessible | ||
|
|
||
| - **No AI-specific dependencies in CI/CD.** The build, test, and lint pipelines use standard open-source tooling. No step requires an AI tool to complete. | ||
| - **CLAUDE.md is documentation, not a gate.** The CLAUDE.md files in our repos serve as developer documentation that happens to also configure AI agents. They document architecture, conventions, and commands that benefit all contributors. | ||
| - **Enhancement proposals are human-readable.** Design documents in `enhancement-proposals/` are written for human review and discussion, regardless of how the initial draft was produced. | ||
|
|
||
|
|
||
| ### AI Workflow Tooling | ||
|
|
||
| OSAC contributors are adopting AI workflow tools - including GSD workflows, MCP plugins, and AI coding skills - to accelerate development. These tools are open source and available to all contributors. We encourage the community to adopt, improve, and contribute to these workflows alongside the code itself. | ||
|
|
||
| To ensure no contributor is disadvantaged: | ||
|
|
||
|
|
||
| - All project decisions and discussions happen on GitHub | ||
| - Contributors can reproduce builds, run tests, and submit PRs without any AI tooling | ||
| - No build, test, or deployment specification may require AI-specific tools to execute | ||
| - Workflow artifacts (`.planning/` directories, GSD state files) provide useful context but aren’t required for contribution | ||
| - **Workflow state files must not be committed.** Session-specific artifacts (`STATE.md`, `SESSION*.md`, `*.lock`, `HANDOFF*.md`, `*.gsd`) vary per developer and cause merge conflicts. Each repo’s `.gitignore` should exclude these. Curated reference documents (e.g., architecture analysis under `.planning/codebase/`) may be committed deliberately when they have lasting value for the team | ||
|
|
||
| ## AI Disclosure Requirements | ||
|
|
||
| ### When to disclose | ||
|
|
||
| Contributors should use the appropriate trailer in commit messages to disclose AI usage, following the conventions established by the OpenInfra Foundation and Red Hat: | ||
|
|
||
| - **`Generated-By:`** - when AI tools were used for **substantive** code generation (e.g., writing functions, implementing features, generating tests). This is the default for agentic coding workflows. | ||
| - **`Assisted-By:`** - when AI tools provided lighter assistance (e.g., debugging help, design suggestions, code review feedback) but the human wrote the code. | ||
|
|
||
| ### What the disclosure means | ||
|
|
||
| The `Generated-By:` / `Assisted-By:` trailers are informational. They: | ||
| - Helps reviewers understand the contribution's origin | ||
| - Builds a transparent development culture | ||
| - Does NOT imply lower quality or trigger additional review gates | ||
| - Does NOT affect copyright assignment (the human contributor remains the author) | ||
|
|
||
| ## Code Review Standards | ||
|
|
||
| ### All contributions (AI-assisted or not) | ||
|
|
||
| Every PR must meet the same quality bar: | ||
|
|
||
| 1. **Passes CI** - all linting, unit tests, integration tests, and end-to-end tests pass. QE-driven feature testing adds an additional layer of intent and side-effect validation. | ||
| 2. **Follows conventions** - naming, patterns, and architecture documented in CLAUDE.md and codebase conventions | ||
| 3. **Has adequate test coverage** - new functionality includes tests; bug fixes include regression tests | ||
| 4. **Is reviewable** - reasonable PR size, clear commit messages, focused scope | ||
|
|
||
| ### Additional expectations for AI-assisted contributions | ||
|
|
||
| Reviewers should pay particular attention to: | ||
|
|
||
| | Review focus | Why | | ||
| |---|---| | ||
| | **Edge cases and error handling** | AI tools may generate happy-path code that misses failure modes | | ||
| | **Security implications** | AI-generated code may introduce subtle vulnerabilities (injection, improper validation, leaked secrets) | | ||
| | **Unnecessary complexity** | AI tools sometimes over-engineer solutions or add unused abstractions | | ||
| | **Copy-paste patterns** | AI may duplicate code instead of reusing existing utilities | | ||
| | **License compatibility** | Verify no externally-sourced snippets with incompatible licenses were introduced | | ||
| | **Test quality** | AI-generated tests may test the implementation rather than the behavior (tautological tests) | | ||
|
|
||
| ### The "explain your code" standard | ||
|
|
||
| - **Do** interrogate your AI agent until you understand every edge case and interaction in your changes. | ||
| - **Don't** submit code you can't explain without your agent open. | ||
| - **Don't** use agents as a substitute for understanding the system. Read the architecture docs. | ||
|
|
||
| Reviewers may ask contributors to explain specific implementation choices. "The AI wrote it this way" is not an acceptable answer. If a contributor cannot explain their code, the PR should not be merged. | ||
|
|
||
| ## Legal & Licensing Considerations | ||
|
|
||
| ### Developer Certificate of Origin (DCO) | ||
|
|
||
| OSAC uses the Apache 2.0 license. Contributors sign off on their commits via the DCO (`Signed-off-by:`), certifying they have the right to submit the contribution. | ||
|
|
||
| When using AI tools: | ||
| - The human contributor remains the legal author and is responsible for the DCO sign-off | ||
| - AI tools cannot sign the DCO - only humans can certify contribution rights | ||
| - Contributors should be aware that AI-generated code may inadvertently reproduce training data; use judgment and review output carefully | ||
|
|
||
| ### Copyright | ||
|
|
||
| - US courts have affirmed that purely AI-generated works may lack copyright protection | ||
| - In practice, AI-assisted code (where a human directs, reviews, and modifies the output) retains human authorship | ||
| - Contributors retain copyright of their contributions under the Apache 2.0 license, consistent with existing project policy | ||
|
|
||
| ## Reviewer Guidelines | ||
|
|
||
| ### For maintainers reviewing AI-assisted PRs | ||
|
|
||
| 1. **Apply the same standards** - don't lower the bar because "AI wrote it" and don't raise it either | ||
| 2. **Check understanding** - if something looks generated, ask the contributor to explain the design choice | ||
| 3. **Watch for AI patterns** - overly verbose comments, unnecessary abstractions, boilerplate that doesn't match project style | ||
| 4. **Verify tests are meaningful** - ensure tests validate behavior, not just that the code compiles | ||
| 5. **Trust but verify** - AI-assisted code can be excellent; don't assume it's wrong, but do review it thoroughly | ||
|
|
||
| ### For contributors submitting AI-assisted PRs | ||
|
|
||
| 1. **Review your own code first** - read every line before submitting; you are the first reviewer | ||
| 2. **Test locally** - run the full test suite, not just the tests the AI wrote | ||
| 3. **Simplify** - if the AI over-engineered something, simplify it before submitting | ||
| 4. **Disclose** - add the appropriate `Generated-By:` or `Assisted-By:` trailer | ||
| 5. **Be ready to explain** - understand why every line exists | ||
|
|
||
| ## What This Policy Does NOT Do | ||
|
|
||
| - **Mandate AI usage** - no contributor is required to use AI tools | ||
| - **Ban AI usage** - AI tools are encouraged for all contributors | ||
| - **Create a two-tier review process** - all code meets the same quality bar | ||
| - **Require specific AI tools** - use whatever tools work for you | ||
| - **Block external contributors** - all essential workflows work without Red Hat-internal tooling | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CLAUDE.mdis vendor specific, other tools look forAGENTS.md.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair point on vendor specificity. Here is why we are approaching it this way for now:
Broad support: Most major AI tools currently read CLAUDE.md by default anyway.
Double duty: The "guidelines" an agent needs (build commands, conventions, known quirks) are the exact same quick-reference docs a human contributor needs.
Future transition: Once Claude Code natively supports AGENTS.md, we will move shared instructions there and reserve CLAUDE.md strictly for Claude-specific configs (like skills and hooks).
To address this, I've added - https://github.com/osac-project/docs/pull/26/changes#diff-fa8c00fbd3ada16d7c08c8e6c9277c975e97bf47c042628dc8a0b6ebfcaea6e5R22