Skip to content

Comments

Shrinks CLAUDE.md after applying ambient claude.md generator#643

Open
markturansky wants to merge 2 commits intoambient-code:mainfrom
markturansky:improvement/claudemd_size2
Open

Shrinks CLAUDE.md after applying ambient claude.md generator#643
markturansky wants to merge 2 commits intoambient-code:mainfrom
markturansky:improvement/claudemd_size2

Conversation

@markturansky
Copy link

@markturansky markturansky commented Feb 16, 2026

My prompt:

read this source for workflow and do it https://github.com/ambient-code/workflows/tree/main/workflows/claude-md-generator

@markturansky markturansky mentioned this pull request Feb 16, 2026
Closed
@github-actions

This comment has been minimized.

Sign in to view
@jeremyeder
Copy link
Collaborator

jeremyeder commented Feb 18, 2026

Let's use this one instead of #641.

@markturansky
Copy link
Author

markturansky commented Feb 18, 2026

Ok. i think i missed a few checkins. There are pointers in claude.md but are missing files. i will follow up shortly

@markturansky @claude
Add BOOKMARKS.md for progressive disclosure of project documentation
6409973 
Referenced from CLAUDE.md but was missing from the commit.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@markturansky
Copy link
Author

markturansky commented Feb 18, 2026

@jeremyeder I added the single filed I missed (BOOKMARKS.md). This PR is ready.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 18, 2026 •
edited
Loading

Claude Code Review

Summary

This PR successfully implements the ambient claude.md generator workflow, reducing CLAUDE.md from 1,168 lines to 73 lines while adding a comprehensive BOOKMARKS.md (224 lines) for progressive disclosure. The refactoring achieves the primary goal of making project documentation more maintainable and accessible through structured, task-specific references.

Net Result: -1,095 lines of redundant content, replaced with a lean master file + organized bookmark system

Issues by Severity

🚫 Blocker Issues

None - The PR is structurally sound and follows established patterns.

🔴 Critical Issues

1. Broken Documentation Links ⚠️

Several files referenced in BOOKMARKS.md do not exist in the repository:

Missing files:

  • docs/developer/local-development/crc.md (referenced in Deployment & Operations)
  • docs/deployment/OPENSHIFT_DEPLOY.md (referenced in Deployment & Operations)
  • docs/deployment/OPENSHIFT_OAUTH.md (referenced in Deployment & Operations)
  • docs/deployment/git-authentication.md (referenced in Deployment & Operations)
  • docs/testing/e2e-guide.md (referenced in Testing)
  • docs/testing/testing-summary.md (referenced in Testing)
  • docs/integrations/GITHUB_APP_SETUP.md (referenced in Integrations)
  • docs/integrations/gitlab-integration.md (referenced in Integrations)
  • docs/integrations/google-workspace.md (referenced in Integrations)
  • docs/deployment/langfuse.md (referenced in Observability)
  • docs/observability/README.md (referenced in Observability)
  • docs/observability/operator-metrics-visualization.md (referenced in Observability)
  • docs/design/declarative-session-reconciliation.md (referenced in Design Documents)
  • docs/design/runner-operator-contract.md (referenced in Design Documents)
  • docs/design/session-status-redesign.md (referenced in Design Documents)

Impact: Users following BOOKMARKS.md will encounter 404 errors, undermining the purpose of the progressive disclosure system.

Recommendation: Either:

  1. Create placeholder/stub files for the missing documentation
  2. Remove references to non-existent files from BOOKMARKS.md
  3. Update links to point to existing documentation that covers these topics

🟡 Major Issues

2. Missing Validation of Link Targets

The PR doesn't include any automated validation that all referenced files in BOOKMARKS.md actually exist. This creates a maintenance burden.

Recommendation: Add a CI check or pre-commit hook to validate all markdown links in BOOKMARKS.md point to existing files.

3. No Backward Compatibility Note

The PR drastically changes CLAUDE.md structure. While this is intentional, there's no migration note for contributors who may have bookmarked specific sections of the old CLAUDE.md.

Recommendation: Add a brief migration note at the top of the new CLAUDE.md pointing users to BOOKMARKS.md for detailed documentation.

🔵 Minor Issues

4. Inconsistent Link Formatting

Some sections in BOOKMARKS.md use consistent formatting while others vary slightly. For example:

  • Some descriptions are complete sentences with periods
  • Others are sentence fragments without periods

Example:

  • ✓ "Go backend patterns, K8s integration, handler conventions, user-scoped client usage." (has period)
  • ✗ "NextJS patterns, Shadcn UI usage, React Query data fetching, component guidelines" (no period)

Recommendation: Standardize description formatting throughout BOOKMARKS.md.

5. Missing BOOKMARKS.md Context in CLAUDE.md

The new CLAUDE.md references BOOKMARKS.md at the end but doesn't explain when to use it or how it differs from the memory system files (.claude/context/, .claude/patterns/).

Recommendation: Add a brief "How to Use This Repository" section explaining:

  • CLAUDE.md = Quick reference for structure and critical rules
  • BOOKMARKS.md = Find detailed docs by topic
  • .claude/* = Loadable memory system for specific tasks

Positive Highlights

✅ Excellent Progressive Disclosure Design
The BOOKMARKS.md structure is well-organized with clear categorization (Architecture Decisions, Development Context, Code Patterns, etc.).

✅ Preserved Critical Context
All critical rules from the original CLAUDE.md are preserved in the condensed version:

  • User token auth requirements
  • OwnerReferences on child resources
  • No panic() in production
  • No any types in frontend
  • Conventional commits

✅ Follows Project Standards
The new CLAUDE.md structure aligns with the ambient claude.md generator workflow approach, making it easier for other projects to adopt this pattern.

✅ Significant Reduction in Cognitive Load
Reducing CLAUDE.md from 1,168 lines to 73 lines makes it much more approachable for new contributors while still providing navigation to detailed documentation.

✅ Well-Structured Table of Contents
The BOOKMARKS.md table of contents provides quick navigation to all major documentation areas.

✅ Preserved Session Flow Diagram
The critical session flow diagram is retained in the condensed CLAUDE.md, providing essential architecture understanding at a glance.

Recommendations

Priority 1 (Before Merge)

  1. Fix broken links - Either create missing docs or remove dead links from BOOKMARKS.md
  2. Add link validation - Implement automated checks for broken documentation links

Priority 2 (Soon After Merge)

  1. Add migration guide - Brief note in CLAUDE.md explaining the restructure
  2. Standardize formatting - Make description formatting consistent throughout BOOKMARKS.md
  3. Add usage guide - Explain relationship between CLAUDE.md, BOOKMARKS.md, and .claude/* files

Priority 3 (Future Enhancement)

  1. Consider adding examples - Show example workflows like "I'm adding a backend endpoint" → Load these files
  2. Add visual hierarchy - Consider using emojis or other visual markers for different doc types in BOOKMARKS.md

Code Quality Assessment

Aspect Rating Notes
Structure ✅ Excellent Clean separation of concerns
Maintainability ✅ Excellent Much easier to maintain than 1,168-line file
Documentation Quality ⚠️ Good Needs broken links fixed
Follows Standards ✅ Excellent Aligns with CLAUDE.md patterns
Accessibility ✅ Excellent Progressive disclosure improves findability

Final Verdict

Conditional Approval - This is a well-executed refactoring that significantly improves documentation organization. However, the broken documentation links are a critical issue that must be addressed before merge.

The fundamental approach is sound and aligns with best practices for progressive disclosure in technical documentation. Once the broken links are fixed, this will be a valuable improvement to the repository.

Action Required: Fix or remove the 15 broken documentation links in BOOKMARKS.md before merging.

🤖 Generated with Claude Code - Code Review Agent

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

  1. CLAUDE.md - Master project instructions, development standards
  2. backend-development.md - Go backend, K8s integration patterns
  3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
  4. security-standards.md - Auth, RBAC, token handling
  5. k8s-client-usage.md - User token vs service account patterns
  6. error-handling.md - Consistent error patterns
  7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

@markturansky
Copy link
Author

markturansky commented Feb 20, 2026

PR #643 Review Coverage Report

Comprehensive audit of all review feedback against the current branch state (improvement/claudemd_size2 @ 6409973).

Human Comments

< /dev/null | # | Author | Issue | Status | Detail |
|---|--------|-------|--------|--------|
| H1 | jeremyeder | Use this PR instead of #641 | ✅ Ack | Procedural — this PR is the active one |
| H2 | markturansky | Missing files referenced in CLAUDE.md | ✅ Fixed | BOOKMARKS.md added in 6409973 |

Automated Review 1 (outdated, minimized) — Blocker

# Issue Status Detail
R1-B1 Missing BOOKMARKS.md — CLAUDE.md references file that doesn't exist ✅ Fixed BOOKMARKS.md added in commit 6409973 with 224 lines of progressive disclosure content

Automated Review 1 — Critical Issues

# Issue Status Detail
R1-C1 Loss of Amber background agent documentation ✅ Fixed BOOKMARKS.md includes dedicated "Amber Automation" section linking to docs/amber-quickstart.md, docs/amber-automation.md, .claude/amber-config.yml — all files verified to exist
R1-C2 Memory system instructions removed (when to load context files) ⚠️ By Design CLAUDE.md delegates to BOOKMARKS.md which links to all .claude/context/ and .claude/patterns/ files. No explicit "when to load" guidance, but progressive disclosure replaces it
R1-C3 Development workflow context lost (hot-reload, component testing) ✅ Fixed CLAUDE.md retains per-component commands section with gofmt, go vet, golangci-lint, npm run build, uv pip install, mkdocs serve

Automated Review 1 — Major Issues

# Issue Status Detail
R1-M1 Security standards not surfaced ✅ Fixed CLAUDE.md "Critical Context" section preserves: user token auth, OwnerReferences, no panic(), no any types. BOOKMARKS.md links to .claude/context/security-standards.md
R1-M2 Testing strategy completely removed ✅ Fixed CLAUDE.md includes make test and make test-e2e-local. BOOKMARKS.md has full "Testing" section linking to docs/testing/e2e-guide.md, e2e/README.md, docs/testing/testing-summary.md
R1-M3 Multi-repo support pattern removed ⚠️ By Design Architectural detail delegated to .claude/context/ memory files and ADR-0003 (linked from BOOKMARKS.md)

Automated Review 1 — Minor Issues

# Issue Status Detail
R1-m1 Container image config details lost ✅ OK Discoverable via Makefile; not needed in top-level CLAUDE.md
R1-m2 Documentation standards not preserved ⚠️ By Design Intentional reduction — standards enforced by PR review process
R1-m3 Git workflow conventions missing ✅ Fixed "Conventional commits: Squashed on merge to main" preserved in Critical Context section

Automated Review 2 — Blocker Issues

# Issue Status Detail
R2-B None identified ✅ —

Automated Review 2 — Critical: 15 Broken Documentation Links in BOOKMARKS.md

All 15 files flagged as missing have been verified to exist on the current branch:

# Referenced Path Status
1 docs/developer/local-development/crc.md ✅ Exists
2 docs/deployment/OPENSHIFT_DEPLOY.md ✅ Exists
3 docs/deployment/OPENSHIFT_OAUTH.md ✅ Exists
4 docs/deployment/git-authentication.md ✅ Exists
5 docs/testing/e2e-guide.md ✅ Exists
6 docs/testing/testing-summary.md ✅ Exists
7 docs/integrations/GITHUB_APP_SETUP.md ✅ Exists
8 docs/integrations/gitlab-integration.md ✅ Exists
9 docs/integrations/google-workspace.md ✅ Exists
10 docs/deployment/langfuse.md ✅ Exists
11 docs/observability/README.md ✅ Exists
12 docs/observability/operator-metrics-visualization.md ✅ Exists
13 docs/design/declarative-session-reconciliation.md ✅ Exists
14 docs/design/runner-operator-contract.md ✅ Exists
15 docs/design/session-status-redesign.md ✅ Exists

Additionally, all 27 other links in BOOKMARKS.md (ADRs, .claude/ files, component READMEs, etc.) were verified — 42/42 links point to existing files.

Automated Review 2 — Major Issues

# Issue Status Detail
R2-M1 Missing link validation in CI ℹ️ Suggestion Nice-to-have; not a merge blocker
R2-M2 No backward compatibility note for old CLAUDE.md users ℹ️ Suggestion Nice-to-have; BOOKMARKS.md reference at bottom of CLAUDE.md serves this purpose

Automated Review 2 — Minor Issues

# Issue Status Detail
R2-m1 Inconsistent description formatting (periods) ✅ Fixed All 42 descriptions in BOOKMARKS.md end with periods — formatting is consistent
R2-m2 No explanation of how CLAUDE.md / BOOKMARKS.md / .claude/* relate ⚠️ By Design CLAUDE.md points to BOOKMARKS.md; BOOKMARKS.md links to .claude/ files. Relationship is implicit through structure

Summary

Category Total ✅ Fixed/OK ⚠️ By Design ℹ️ Suggestion
Human comments 2 2 0 0
Review 1 — Blocker 1 1 0 0
Review 1 — Critical 3 2 1 0
Review 1 — Major 3 2 1 0
Review 1 — Minor 3 2 1 0
Review 2 — Broken links 15 15 0 0
Review 2 — Major 2 0 0 2
Review 2 — Minor 2 1 1 0
Total 31 25 4 2

All blocker and critical issues are resolved. All 42 BOOKMARKS.md links verified. PR is ready for re-review.

Generated by auditing branch improvement/claudemd_size2 @ 6409973 against all review comments and automated findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@markturansky @jeremyeder