feat: enable context efficient agent analysis #267
Conversation
arewm
force-pushed
the
lazy-context-loading
branch
from
c597a19 to
45dfc0d
Compare
|
Hm, the ADR/INDEX.md file does the same job as (Also, hack/generate-adr-index is vestigial and should be removed.) |
|
|
Replace outdated RHTAP terminology with Konflux in ADR-0009 and ADR-0022 to reflect current product naming. Signed-off-by: arewm <[email protected]>
This repository is intended to be a record for how the various core and add-on services are designed to work and work with each other. When designing or refining features, this type of information can be instrumental when using AI assistants (i.e. Claude). Changes: - Add CLAUDE.md with context loading rules and architectural constraints - Add CONTRIBUTING.md with AI assistant integration guidance - Add .claude/commands/maintain.md for documentation consistency audits The framework enables lazy loading of context to maximize available context for feature analysis while minimizing token usage. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Signed-off-by: arewm <[email protected]>
Add a quick-reference index to enable efficient ADR discovery without reading full documents. Includes 51 ADR entries with status, summary, and topic tags. Usage pattern: 1. Search this file for keywords (grep) 2. Note the ADR number 3. Read ADR head/tail only (first 30 + last 20 lines) 4. Only read full ADR if critical This supports the lazy context loading framework defined in CLAUDE.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Signed-off-by: arewm <[email protected]>
Configure 11ty build system to exclude AI assistant documentation from the published site: - Add .eleventyignore entries for CLAUDE.md and quick-reference.md - Add eleventyComputed.js to exclude files with exclude_from_publish: true - Update .gitignore for _data directory - Remove deprecated hack/generate-adr-index script - Update ADR table generation and linting scripts - Add @11ty/eleventy-plugin-rss dependency These files are intended for AI assistant context loading, not end-user documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Signed-off-by: arewm <[email protected]>
Add structured metadata to all core and add-on service documentation files to support efficient context loading by AI assistants. Each service now includes: - scope: Service responsibilities and focus areas - key_crds: Primary Kubernetes custom resources - depends_on: Service dependencies - related_adrs: Relevant architecture decisions - key_concepts: Important terminology and patterns This enables AI assistants to quickly determine if a service file contains relevant information without reading the entire document. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> Signed-off-by: arewm <[email protected]>
arewm
force-pushed
the
lazy-context-loading
branch
from
45dfc0d to
5d9426a
Compare
|
@konflux-ci/integration-service-maintainers @konflux-ci/release-service-maintainers @konflux-ci/mintmaker-maintainers @konflux-ci/ec @konflux-ci/build-maintainers @ifireball , would you approve of merging this change? It touches all files but it doesn't affect the content of what is actually included |
Signed-off-by: arewm <[email protected]>
| toc: true | ||
| local_summary: | ||
| scope: "Release orchestration, privileged pipelines, cross-namespace releases" | ||
| key_crds: "Release, ReleasePlan, ReleasePlanAdmission, ReleaseStrategy" |
There was a problem hiding this comment.
ReleaseStrategy no longer exists. Does this still have to be here because historically it existed, or can it be removed?
There was a problem hiding this comment.
This page should be cleaned up/updated to remove the references: https://github.com/konflux-ci/architecture/blob/main/architecture/core/release-service.md?plain=1#L23-L24
| module.exports = { | ||
| permalink: function(data) { | ||
| // If the page's input path starts with ./architecture/ | ||
| // strip that prefix from the output permalink | ||
| if (data.page.inputPath.startsWith('./architecture/')) { | ||
| // Get the path after ./architecture/ | ||
| let path = data.page.inputPath.substring('./architecture/'.length); | ||
|
|
||
| // Handle index.md specially - map to root | ||
| if (path === 'index.md') { | ||
| return '/index.html'; | ||
| } | ||
|
|
||
| // For other files, remove .md extension and add /index.html for clean URLs | ||
| path = path.replace(/\.md$/, '/index.html'); | ||
|
|
||
| return '/' + path; | ||
| } | ||
|
|
||
| // For all other files, use default behavior | ||
| return data.permalink; | ||
| } | ||
| }; |
There was a problem hiding this comment.
The commit message is significantly out of sync with what the commit does. This script is probably the most obvious example.
On a related note: what does this do?
There was a problem hiding this comment.
The commit message is halfway accurate.
Details
chore: update build pipeline to exclude AI assistant files Configure 11ty build system to exclude AI assistant documentation from the published site: - Add .eleventyignore entries for CLAUDE.md and quick-reference.md - Add eleventyComputed.js to exclude files with exclude_from_publish: true - Update .gitignore for _data directory - Remove deprecated hack/generate-adr-index script - Update ADR table generation and linting scripts - Add @11ty/eleventy-plugin-rss dependencyThese files are intended for AI assistant context loading, not end-user
documentation.
🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]
Signed-off-by: arewm [email protected]
It excludes the AI generated content but it also improves consistency between local and CI rendering of the page.
This file (along with some others like the Makefile changes) fix inconsistencies between rendering the Architecture repo and the production of the site in the GitHub workflows. This file specifically enables better rendering of the architecture directory's index so that we don't have architecture/architecture.
There was a problem hiding this comment.
Ah, yes, I see that now when I run make serve locally.
On main, the landing page is at http://localhost:8080/architecture, with this PR it's directly at http://localhost:8080. Will this not interfere with the actual deployment of the web page, where we do need the /architecture prefix? https://konflux-ci.dev/architecture/
There was a problem hiding this comment.
Also, I noticed the Overview and ADRs links at the top are broken, they still include the /architecture prefix
There was a problem hiding this comment.
It might end up being something to break out of this PR to try to address more comprehensively elsewhere.
There was a problem hiding this comment.
Added documentation to clarify purpose:
This file customizes the permalink structure for published documentation:
- Files in
./architecture/are published with that prefix removed from URLs - Example:
./architecture/core/build-service.md→/core/build-service/ - This allows the repository structure to separate source docs from build config while producing clean URLs without an
/architecture/prefix in the published site
Added a comprehensive header comment (lines 1-9) explaining the purpose and including an example.
Fixed in commit 3c55a0d
Comment drafted with Claude's assistance
There was a problem hiding this comment.
I still see the broken links mentioned in #267 (comment). It might be better to break out those changes into a separate PR as you mentioned
Address PR review feedback to optimize context loading for AI assistants: - Update ADR loading strategy to use subagent processing instead of arbitrary line ranges - Regenerate all 47 ADR summaries from Decision sections (not Context) - Rename local/ to local-analysis/ with explanatory comments - Document eleventyComputed.js purpose with header comment - Update /maintain command to verify ADR quick-reference.md coverage These changes focus exclusively on improving AI analysis efficiency without modifying substantive technical content. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Address PR review feedback: - Change /ADR/INDEX.md to /ADR/quick-reference.md - Note that quick-reference.md can be updated by maintainers after merge - Specify summary should be from Decision section, not Context Addresses comment konflux-ci#267 (comment) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Address PR review feedback to make service frontmatter more generic: 1. Rename `depends_on` → `related_services` in all service files - Better represents service relationships vs strict dependencies - build-service relates to image-controller but doesn't depend on it - Updated description to "Services this service interacts with or relates to" - Update standalone comment from "None (foundational)" to "None (standalone)" 2. Rename `local_summary` → `overview` for frontmatter section name - More generic term not tied to AI assistant tooling - Clearer purpose for general documentation use 3. Update /maintain command to verify all required overview fields - Added check for: scope, key_crds, related_services, related_adrs, key_concepts 4. Update all references in CONTRIBUTING.md, CLAUDE.md, and service files Changes applied to 12 service files + documentation and slash commands. Addresses comment konflux-ci#267 (comment) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
…lazy-context-loading Resolved conflict in architecture/core/pipeline-service.md by accepting upstream changes which include updated Architecture Evolution section with upstream/downstream installation distinction and historical context. Also includes upstream changes: - ADR-0055: SLSA source provenance verification (new) - Updates to ADR-0031, 0039, 0047, 0053, 0054
Completely redesign /maintain command for comprehensive documentation maintenance: **Auto-Fix Capabilities:** - Service list sync (add/remove from CLAUDE.md) - Complete service relationship analysis - ADR quick-reference synchronization - Frontmatter validation and completion - Broken reference cleanup **Intelligent Relationship Detection:** For NEW services (not in CLAUDE.md): - Auto-scans content for service mentions, links, CRD usage - Auto-adds all detected relationships - Auto-updates existing services to reference new service For EXISTING services: - Detects missing relationships via content analysis - Prompts user with evidence (line numbers, quotes, shared ADRs) - Supports bidirectional relationship validation **Relationship Criteria:** 1. Content references - service names/links in documentation 2. CRD usage - uses another service's CRDs 3. CRD ownership - owns CRDs another service uses 4. Shared ADRs - functional overlap indicators 5. Explicit listing - bidirectional implications **Applied Fixes:** - Added ADR-0055 to quick-reference.md - Updated image-controller: added pipeline-service relationship - Updated project-controller: added image-controller relationship Command evolution: Report-only → Comprehensive auto-fix with relationship intelligence 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
7 participants
This repository is intended to be a record for how the various core and add on services are designed to work and work with each other. When designing or refining features, this type of information can be instrumental when using ai assistants (i.e. claude).
This change creates a framework for lazy loading context into ai assistants so that we can maximize the context available for analysis of the features themselves.