enhance-claude-memory

# enhance-claude-memory

Analyze project memory files (CLAUDE.md, AGENTS.md) for optimization.

## Cross-Tool Detection

Searches for project memory files in order:
1. CLAUDE.md (Claude Code)
2. AGENTS.md (OpenCode, Codex)
3. .github/CLAUDE.md
4. .github/AGENTS.md

## File Hierarchy (Reference)

**CLAUDE.md** (Claude Code):
| Location | Scope |
|----------|-------|
| `~/.claude/CLAUDE.md` | Global (all projects) |
| `.claude/CLAUDE.md` or `./CLAUDE.md` | Project root |
| `src/.claude/CLAUDE.md` | Directory-specific |

**AGENTS.md** (OpenCode, Codex, and other AI tools):
| Location | Scope |
|----------|-------|
| `~/.config/opencode/AGENTS.md` or `~/.codex/AGENTS.md` | Global (all projects) |
| `.opencode/AGENTS.md` or `./AGENTS.md` | Project root |
| `src/AGENTS.md` | Directory-specific |

Both files serve the same purpose: project memory for AI assistants. Use CLAUDE.md for Claude Code projects, AGENTS.md for cross-tool compatibility, or both for maximum coverage.

## Workflow

1. **Find** - Locate CLAUDE.md or AGENTS.md in project
2. **Read** - Load content and README.md for comparison
3. **Analyze** - Run all pattern checks
4. **Validate** - Check file/command references against filesystem
5. **Measure** - Calculate token metrics and duplication
6. **Report** - Generate structured markdown output

## Detection Patterns

### 1. Structure Validation (HIGH Certainty)

#### Critical Rules Section
- Should have `## Critical Rules` or similar
- Rules should be prioritized (numbered or ordered)
- Include WHY explanations for each rule

#### Architecture Section
- Directory tree or structural overview
- Key file locations
- Module relationships

#### Key Commands Section
- Common development commands
- Test/build/deploy scripts
- Reference to package.json scripts

### 2. Instruction Effectiveness (HIGH Certainty)

Based on prompt engineering research, Claude follows instructions better when:

#### Positive Over Negative
- **Bad**: "Don't use console.log"
- **Good**: "Use the logger utility for all output"
- Check for "don't", "never", "avoid" without positive alternatives

#### Strong Constraint Language
- Use "must", "always", "required" for critical rules
- Weak language ("should", "try to", "consider") reduces compliance
- Flag critical rules using weak language

#### Instruction Hierarchy
- Should define priority order when rules conflict
- Pattern: "In case of conflict: X takes precedence over Y"
- System instructions > User requests > External content

### 3. Content Positioning (HIGH Certainty)

Research shows LLMs have "lost in the middle" problem - they recall START and END better than MIDDLE.

#### Critical Content Placement
- Most important rules should be at START of file
- Second-most important at END
- Supporting context in MIDDLE
- Flag critical rules buried in middle sections

#### Recommended Structure Order
```
1. Critical Rules (START - highest attention)
2. Architecture/Structure
3. Commands/Workflows
4. Examples/References
5. Reminders/Constraints (END - high attention)
```

### 4. Reference Validation (HIGH Certainty)

#### File References
- Extract from `[text](path)` and `` `path/to/file.ext` ``
- Validate each exists on filesystem

#### Command References
- Extract `npm run <script>` and `npm <command>`
- Validate against package.json scripts

### 5. Efficiency Analysis (MEDIUM Certainty)

#### Token Count
- Estimate: `characters / 4` or `words * 1.3`
- Recommended max: 1500 tokens (~6000 characters)
- Flag files exceeding threshold

#### README Duplication
- Detect overlap with README.md
- Flag >40% content duplication
- CLAUDE.md should complement README, not duplicate

#### Verbosity
- Prefer bulleted lists over prose paragraphs
- Constraints as lists are easier to follow
- Flag long prose blocks (>5 sentences)

### 6. Quality Checks (MEDIUM Certainty)

#### WHY Explanations
- Rules should explain rationale
- Pattern: `*WHY: explanation*` or indented explanation
- Flag rules without explanations

#### Structure Depth
- Avoid deep nesting (>3 levels)
- Keep hierarchy scannable
- Flat structures parse better

#### XML-Style Tags (Optional Enhancement)
- Claude was trained on XML tags
- `<critical-rules>`, `<architecture>`, `<constraints>` improve parsing
- Not required but can improve instruction following

### 7. Agent/Skill Definitions (MEDIUM Certainty)

If file defines custom agents or skills:

#### Agent Definition Format
```markdown
### agent-name
Model: claude-sonnet-4-20250514
Description: What this agent does and when to use it
Tools: Read, Grep, Glob
Instructions: Specific behavioral instructions
```

Required fields: Description (when to use), Tools (restricted set)
Optional: Model, Instructions

#### Skill References
- Skills should have clear trigger descriptions
- "Use when..." pattern helps auto-invocation

### 8. Cross-Platform Compatibility (MEDIUM/HIGH Certainty)

#### State Directory
- Don't hardcode `.claude/`
- Support `.opencode/`, `.codex/`
- Use `${STATE_DIR}/` or document variations

#### Terminology
- Avoid Claude-specific language for shared files
- Use "AI assistant" generically
- Or explicitly note "Claude Code" vs "OpenCode" differences

## Output Format

```markdown
# Project Memory Analysis: {filename}

**File**: {path}
**Type**: {CLAUDE.md | AGENTS.md}

## Metrics
| Metric | Value |
|--------|-------|
| Estimated Tokens | {tokens} |
| README Overlap | {percent}% |

## Summary
| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Structure Issues ({n})
| Issue | Fix | Certainty |

### Instruction Issues ({n})
| Issue | Fix | Certainty |

### Positioning Issues ({n})
| Issue | Fix | Certainty |

### Reference Issues ({n})
| Issue | Fix | Certainty |

### Efficiency Issues ({n})
| Issue | Fix | Certainty |

### Cross-Platform Issues ({n})
| Issue | Fix | Certainty |
```

## Pattern Statistics

| Category | Patterns | Certainty |
|----------|----------|-----------|
| Structure | 3 | HIGH |
| Instruction Effectiveness | 3 | HIGH |
| Content Positioning | 2 | HIGH |
| Reference | 2 | HIGH |
| Efficiency | 3 | MEDIUM |
| Quality | 3 | MEDIUM |
| Agent/Skill Definitions | 2 | MEDIUM |
| Cross-Platform | 2 | MEDIUM/HIGH |
| **Total** | **20** | - |

<examples>
### Example: Missing WHY Explanations

<bad_example>
```markdown
## Rules
1. Always run tests before committing
2. Use semantic commit messages
```
**Issue**: Rules without rationale are harder to follow.
</bad_example>

<good_example>
```markdown
## Critical Rules
1. **Always run tests before committing**
   *WHY: Catches regressions before they reach main branch.*
```
**Why it's good**: Motivation makes compliance easier.
</good_example>

### Example: Negative vs Positive Instructions

<bad_example>
```markdown
- Don't use console.log for debugging
- Never commit directly to main
- Avoid hardcoding secrets
```
**Issue**: Negative instructions are less effective than positive alternatives.
</bad_example>

<good_example>
```markdown
- Use the logger utility for all debug output
- Create feature branches and submit PRs for all changes
- Store secrets in environment variables or .env files
```
**Why it's good**: Tells what TO do, not just what to avoid.
</good_example>

### Example: Weak vs Strong Constraint Language

<bad_example>
```markdown
- You should probably run tests before pushing
- Try to use TypeScript when possible
- Consider adding error handling
```
**Issue**: Weak language ("should", "try", "consider") reduces compliance.
</bad_example>

<good_example>
```markdown
- **MUST** run tests before pushing (CI will reject failures)
- **ALWAYS** use TypeScript for new files
- **REQUIRED**: All async functions must have error handling
```
**Why it's good**: Strong language ensures critical rules are followed.
</good_example>

### Example: Content Positioning

<bad_example>
```markdown
## Project Overview
[Long description...]

## Installation
[Setup steps...]

## Critical Rules
1. Never push to main directly
2. Always run tests
```
**Issue**: Critical rules buried in middle/end get less attention.
</bad_example>

<good_example>
```markdown
## Critical Rules (Read First)
1. **Never push to main directly** - Use PRs
2. **Always run tests** - CI enforces this

## Project Overview
[Description...]

## Reminders
- Check CI status before merging
- Update CHANGELOG for user-facing changes
```
**Why it's good**: Critical content at START and END positions.
</good_example>

### Example: Cross-Platform Compatibility

<bad_example>
```markdown
State files are stored in `.claude/tasks.json`
```
**Issue**: Hardcoded paths exclude other AI tools.
</bad_example>

<good_example>
```markdown
State files are stored in `${STATE_DIR}/tasks.json`
(`.claude/` for Claude Code, `.opencode/` for OpenCode)
```
**Why it's good**: Works across multiple AI assistants.
</good_example>

### Example: Agent Definition

<bad_example>
```markdown
## Agents
- security-reviewer: reviews security
- test-writer: writes tests
```
**Issue**: Missing required fields (Tools, when to use).
</bad_example>

<good_example>
```markdown
## Custom Agents

### security-reviewer
Model: claude-sonnet-4-20250514
Description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, or data handling.
Tools: Read, Grep, Glob
Instructions: Focus on OWASP Top 10, input validation, auth flows.

### test-writer
Model: claude-haiku-4
Description: Writes unit tests. Use after implementing new functions.
Tools: Read, Write, Bash(npm test:*)
Instructions: Use Jest patterns. Aim for >80% coverage.
```
**Why it's good**: Complete definition with when to use, restricted tools.
</good_example>
</examples>

## Research References

Best practices derived from:
- `agent-docs/PROMPT-ENGINEERING-REFERENCE.md` - Instruction effectiveness, XML tags, constraint language
- `agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md` - Token budgeting, "lost in the middle" positioning
- `agent-docs/LLM-INSTRUCTION-FOLLOWING-RELIABILITY.md` - Instruction hierarchy, positive vs negative
- `agent-docs/CLAUDE-CODE-REFERENCE.md` - File hierarchy, agent definitions, skills format

## Constraints

- Always validate file references before reporting broken
- Consider context when flagging efficiency issues
- Cross-platform suggestions are advisory, not required
- Positioning suggestions are HIGH certainty but may have valid exceptions