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
added a commit
to ggallen/fullsend
that referenced
this pull request
May 6, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue fullsend-ai#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 fullsend-ai#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
added a commit
to ggallen/fullsend
that referenced
this pull request
May 7, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue fullsend-ai#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 fullsend-ai#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
added a commit
to ggallen/fullsend
that referenced
this pull request
May 7, 2026
…on decisions Resolves remaining low-priority review comments: **Code Comments (Low Issue fullsend-ai#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 fullsend-ai#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
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)