docs: Add codebase context problem document and trim CLAUDE.md - #3
Merged
Conversation
Prevents .worktrees/ contents from being tracked. Assisted-by: Claude Code (Opus 4.6) Signed-off-by: arewm <arewm@users.noreply.github.com>
The structure block duplicated content from README.md and was already out of date (missing recently added problem documents). Per research on agent context files, duplicated information that agents can discover from the filesystem actively hurts performance. Replace with a pointer to README.md. Reduces CLAUDE.md from 47 to 25 lines. Non-obvious content (how to work in this repo, key design decisions) is preserved. Assisted-by: Claude Code (Opus 4.6) Signed-off-by: arewm <arewm@users.noreply.github.com>
Agents are stateless and need structured context to operate effectively. Research shows verbose or auto-generated context files hurt performance, while minimal human-written files help. No existing problem document addresses how agents acquire codebase understanding or how the org should structure information across repos. Proposes a layered context model (code → per-repo → org-level → external) with specific recommendations for the architecture repo: structured frontmatter on service docs and ADRs, a minimal CLAUDE.md, and documented API standards for the emerging API Review SIG. Assisted-by: Claude Code (Opus 4.6) Signed-off-by: arewm <arewm@users.noreply.github.com>
ralphbean
approved these changes
Mar 9, 2026
north-echo
added a commit
to north-echo/fullsend
that referenced
this pull request
Apr 1, 2026
Addresses fullsend-ai#121 with the adjustments proposed in the issue discussion: - Ranked DOS fullsend-ai#3 in the threat priority list (between insider threat and agent drift) - Placed the new section after temporal split-payload and before cross-cutting principles - Cross-referenced Threat 2 rate limiting instead of duplicating it - Trimmed defense considerations to focus on agentic-unique defenses - Consolidated overlapping open questions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3 tasks
5 tasks
This was referenced Apr 23, 2026
Closed
ascerra
added a commit
to ascerra/fullsend
that referenced
this pull request
Apr 29, 2026
- Move inline ${{ }} PR_URL to env: block for consistent env-passing
- Build minimal dispatch payloads for both fix jobs (bot + human)
to avoid exceeding GitHub's 65KB workflow_dispatch input limit
- Add minItems: 1 to actions array in fix-result.schema.json
- Render strategy_change field in process-fix-result.py summary
- Add allOf/if/then conditional schema tests (fix missing description,
disagree missing reason, empty actions rejected)
Tested on ascerra-fullsend-lab:
Run 25085229338 — all steps passed, agent posted summary on PR fullsend-ai#3
Made-with: Cursor
ascerra
added a commit
to ascerra/fullsend
that referenced
this pull request
Apr 29, 2026
- Move inline ${{ }} PR_URL to env: block for consistent env-passing
- Build minimal dispatch payloads for both fix jobs (bot + human)
to avoid exceeding GitHub's 65KB workflow_dispatch input limit
- Add minItems: 1 to actions array in fix-result.schema.json
- Render strategy_change field in process-fix-result.py summary
- Add allOf/if/then conditional schema tests (fix missing description,
disagree missing reason, empty actions rejected)
Tested on ascerra-fullsend-lab:
Run 25085229338 — all steps passed, agent posted summary on PR fullsend-ai#3
Made-with: Cursor
ggallen
referenced
this pull request
in ggallen/fullsend
May 6, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue #3):** - Document intentional asymmetry between enable --all and disable --all - enable --all: discovers current org repos via ListOrgRepos - disable --all: iterates cfg.Repos (handles deleted repos needing cleanup) **Concurrency Safety (Low Issue #4):** - Document read-modify-write pattern in loadRepoConfig - Acknowledge lack of optimistic concurrency control - Explain why this is acceptable for admin CLI usage - Note that production systems would use conditional writes (ETags) **Remaining Action Items:** - PR description needs manual update on GitHub to replace "mutual exclusivity enforcement" with "when --all is set, positional repository arguments are silently ignored" All tests pass (unrelated flake in run_test.go due to network timeout). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
ggallen
referenced
this pull request
in ggallen/fullsend
May 7, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue #3):** - Document intentional asymmetry between enable --all and disable --all - enable --all: discovers current org repos via ListOrgRepos - disable --all: iterates cfg.Repos (handles deleted repos needing cleanup) **Concurrency Safety (Low Issue #4):** - Document read-modify-write pattern in loadRepoConfig - Acknowledge lack of optimistic concurrency control - Explain why this is acceptable for admin CLI usage - Note that production systems would use conditional writes (ETags) **Remaining Action Items:** - PR description needs manual update on GitHub to replace "mutual exclusivity enforcement" with "when --all is set, positional repository arguments are silently ignored" All tests pass (unrelated flake in run_test.go due to network timeout). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
ggallen
referenced
this pull request
in ggallen/fullsend
May 7, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue #3):** - Document intentional asymmetry between enable --all and disable --all - enable --all: discovers current org repos via ListOrgRepos - disable --all: iterates cfg.Repos (handles deleted repos needing cleanup) **Concurrency Safety (Low Issue #4):** - Document read-modify-write pattern in loadRepoConfig - Acknowledge lack of optimistic concurrency control - Explain why this is acceptable for admin CLI usage - Note that production systems would use conditional writes (ETags) **Remaining Action Items:** - PR description needs manual update on GitHub to replace "mutual exclusivity enforcement" with "when --all is set, positional repository arguments are silently ignored" All tests pass (unrelated flake in run_test.go due to network timeout). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This was referenced May 12, 2026
ggallen
referenced
this pull request
in ggallen/fullsend
May 14, 2026
Medium: - Updated PR description to reflect that pre-existing plan links were removed from README (no longer claims to link agent-execution-environment, vertex-inference-provisioning, and drift-scanner) Low #2: - Removed "Minimal wrapper pattern" section from plan document as it argues against itself - describes a pattern that requires capabilities that don't exist yet, then recommends removing it Low #3: - Updated IsURL function comment to note that url.Parse may not set u.User for all userinfo edge cases, advising implementers to consider additional validation if strict userinfo rejection is required Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This was referenced May 21, 2026
This was referenced May 26, 2026
4 tasks
12 tasks
This was referenced Jul 27, 2026
This was referenced Aug 3, 2026
9 tasks
This was referenced Aug 14, 2026
This was referenced Aug 20, 2026
10 tasks
This was referenced Aug 25, 2026
3 tasks
3 tasks
This was referenced Sep 1, 2026
8 tasks
This was referenced Sep 9, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Adds a new problem document addressing how agents acquire codebase understanding and how the org should structure information to enable that. Proposes a layered context model (code → per-repo → org-level → external) with specific recommendations for the architecture repo: structured YAML frontmatter on service docs and ADRs, a minimal CLAUDE.md, and documented API standards for the emerging API Review SIG.
Grounded in ETH Zürich (2026) research showing that verbose context files hurt agent performance. Connects to the API review discussion on the konflux mailing list.
Also trims this repo's own CLAUDE.md from 47 to 25 lines by removing the repository structure listing (which duplicated README.md and was already stale), applying the principles from the new document.
Assisted-by: Claude Code (Opus 4.6)