Skip to content

Commit 6b89778

Browse files
PatrickSysclaude
PatrickSys
and
claude
committed
fix: guard null chunk.content crash + docs rewrite for v1.6.1
Critical fix: search_codebase crashed on ~23% of queries when chunks had null content. Guarded all chunk.content access in detectChunkTrend, generateSummary, and generateSnippet. Also changed pattern warning prefix from emoji to plain text for better cross-platform compatibility. Docs: - README rewritten with pain-first positioning and correct technical claims (Fuse.js + RRF, not BM25) - Added docs/capabilities.md as public technical reference - MOTIVATION.md rewritten - package.json description and keywords updated Tests: - Auto-heal test now uses isolated temp workspace (deterministic) - Added missing-query validation test - Added get_style_guide limited mode test Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0d94029 commit 6b89778

File tree

15 files changed

+510
-343
lines changed

15 files changed

+510
-343
lines changed

‎AGENTS.md‎

Lines changed: 0 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -67,37 +67,3 @@ If any agent violates these rules:
6767
5. **Delay the release** until honest metrics are available
6868

6969
These rules exist because **trustworthiness is more valuable than a good-looking number**.
70-
71-
## Codebase Context
72-
73-
**At start of each task:** Call `get_memory` to load team conventions.
74-
75-
**CRITICAL:** When user says "remember this" or "record this":
76-
77-
- STOP immediately and call `remember` tool FIRST
78-
- DO NOT proceed with other actions until memory is recorded
79-
- This is a blocking requirement, not optional
80-
81-
## Internal Documentation (Submodule)
82-
83-
This repository uses a private git submodule for internal notes.
84-
85-
- **Path**: `internal-docs/`
86-
- **Repo**: `https://github.com/PatrickSys/codebase-context-internal.git`
87-
88-
### Quick Setup
89-
90-
```bash
91-
git clone --recurse-submodules https://github.com/PatrickSys/codebase-context.git
92-
```
93-
94-
### Syncing
95-
96-
```bash
97-
git pull --recurse-submodules
98-
git submodule update --remote --merge
99-
```
100-
101-
### Privacy
102-
103-
The `internal-docs` repository is private. It returns a 404 to unauthenticated users. Access requires a GitHub PAT or SSH keys with repository permissions.

‎MOTIVATION.md‎

Lines changed: 40 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,65 @@
1-
# Motivation: Why This Exists
1+
# Why This Exists
22

33
> **TL;DR**: AI coding assistants increase throughput but often degrade stability. Without codebase context, they generate code that works but violates team conventions and architectural rules. This MCP provides structured pattern data and recorded rationale so agents produce code that fits.
44
5-
---
5+
The generated code compiles, passes basic tests, and completely ignores how your team does things or the business context. You fix it, correct the agent, and next session it starts from zero again. Even if you have curated instructions, you cannot note down every convention your team has and it is hard to maintain over time.
66

77
## The Problem
88

9-
### The "Stability Paradox"
10-
AI drastically increases **Throughput** (more code/hour) but often kills **Stability** (more bugs/rework).
9+
AI agents don't fail because they lack "best practices." They fail because they don't know _your_ practices.
1110

12-
| Pain Point | Evidence |
13-
|------------|----------|
14-
| **"AI doesn't know my codebase"** | 64.7% of developers cite lack of codebase context as top AI challenge ([Stack Overflow 2024](https://survey.stackoverflow.co/2024/ai)) |
15-
| **"Vibe coding" = Tech Debt** | Code churn doubled, rework increased. AI writes "working" code that breaks architectural rules ([GitClear 2024](https://www.gitclear.com/)) |
16-
| **The "Mirror Problem"** | Semantic search just finds *similar* code. If 80% of your code is legacy/deprecated, AI will copy it. The tool becomes a mirror reflecting your bad habits. |
17-
| **Trust gap** | Only 29% of developers trust AI output. Teams spend more time reviewing AI code than writing it. |
11+
| What happens | Why |
12+
| ------------------------------------------ | ----------------------------------------------------------------- |
13+
| Agent uses a deprecated pattern | Can't distinguish modern from legacy when exploring your codebase |
14+
| Agent ignores your internal wrappers | Doesn't know they exist — picks raw library imports |
15+
| Agent invents patterns that don't exist | Makes up variable names, component names, CSS tokens |
16+
| Agent repeats a mistake you corrected | No memory across sessions |
17+
| Agent edits confidently with weak evidence | No way to know when it doesn't know enough |
1818

19-
### What Existing Tools Don't Solve
19+
The root cause isn't the model. It's the context layer. Agents get raw code from search and generic rules from static files. No signal about what's current vs legacy, no team patterns, no memory.
2020

21-
| Tool Category | What They Do | The Gap |
22-
|---------------|--------------|---------|
23-
| **AGENTS.md / .cursorrules** | Static instructions (Intent) | Can't handle migration states (e.g., "Use A for new, B for old"). Static = brittle. |
24-
| **Semantic Search (RAG)** | Finds *relevant* text | Blind to *quality*. Can't distinguish "High Churn Hotspot" from "Stable Core". |
25-
| **Linters** | Complain *after* coding | Don't guide *during* generation. |
21+
## What Exists Today (and the missing context)
2622

27-
---
23+
| Approach | What it does | What's missing |
24+
| ---------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
25+
| `.cursorrules` / `AGENTS.md` | Static rules the agent may or may not always follow | Can't express migration states ("use A for new code, B for old"). Goes stale. |
26+
| Semantic search / RAG | Finds similar code | Blind to quality. Can't tell the best example to follow from hacky workarounds. |
27+
| Linters / formatters | Enforce static rules after writing | Don't guide before or during generation. Agent still writes wrong code first. |
28+
| Tool-heavy MCPs (50+ tools) | Expose everything | Agents don't know which tool to call. More tools = more confusion. |
2829

29-
## What This Does
30+
## What This MCP Does Differently
3031

31-
This MCP provides **active context** - not raw data, but structured intelligence derived from actual codebase state.
32+
### Active context, not passive instructions
3233

33-
### 1. Pattern Discovery (The "Map")
34-
- **Frequency Detection**: "97% use `inject()`, 3% use `constructor`." (Consensus)
35-
- **Internal Library Support**: "Use `@company/button`, not `p-button`." (Wrapper Detection)
36-
- **Golden Files**: "Here is the *best* example of a Service, not just *any* example."
34+
When the agent searches, it doesn't get raw code. It gets code with codebase intelligence attached:
3735

38-
### 2. Temporal Wisdom (The "Compass")
39-
- **Pattern Momentum**: "Use `Signals` (Rising), avoid `BehaviorSubject` (Declining)."
40-
- **Health Context**: "⚠️ Careful, `UserService.ts` is a high-churn hotspot with circular dependencies. Add tests."
36+
- Is this file using a new or legacy pattern?
37+
- What other files import it?
38+
- What team decisions relate to this area?
39+
- Is the context evidence strong enough to edit?
40+
- What conventions should the Agent prefer and what to avoid?
4141

42-
### Works with AGENTS.md
43-
- **AGENTS.md** defines intent: "Use functional patterns."
44-
- **MCP** provides evidence: "Here are the 5 most recent functional patterns actually used."
42+
### Conventions from code, not from documentation
4543

46-
---
44+
Pattern detection runs on the actual codebase, not only on rules someone wrote. If 97% of the team uses the (Angular) `inject()` function for DI over constructor DI and it's trending up, the agent knows - even if nobody documented it.
4745

48-
## Known Limitations
46+
### Memory that compounds
4947

50-
| Limitation | Mitigation |
51-
|------------|--------|
52-
| **Pattern frequency ≠ pattern quality** | **Pattern Momentum** (Rise/Fall trends) distinguishes adoption direction from raw count. |
53-
| **Stale index risk** | Manual re-indexing required for now. |
54-
| **Framework coverage** | Deep analysis for Angular. Generic analyzer covers 30+ languages. React/Vue specialized analyzers extensible. |
55-
| **File-level trend detection** | Trend is based on file modification date, not line-by-line content. A recently modified file may still contain legacy patterns on specific lines. Future: AST-based line-level detection. |
48+
Correct the agent once. Record the decision. From then on, it surfaces in search results and the "preflight" cards - that safeguard AI Agents from generating code that "just compiles". Memories age with confidence decay so stale guidance gets flagged instead of blindly trusted.
5649

57-
---
50+
### Evidence gating
5851

59-
## Key Learnings (The Journey)
52+
Before an edit, the agent gets a curated "preflight" check from three sources (code, patterns, memories). If evidence is thin or contradictory, the response tells the AI Agent to look for more evidence with a concrete next step. This is the difference between "confident assumption" and "informed decision."
6053

61-
1. **Context alone is dangerous**: Giving AI "all the context" just confuses it or teaches it bad habits (Search Contamination).
62-
2. **Decisions > Data**: AI needs *guidance* ("Use X"), not just *options* ("Here is X and Y").
63-
3. **Governance through Discovery**: Blocking PRs is not required. If the AI sees that a pattern is "Declining" and "Dangerous," it self-corrects.
54+
## Key Design Decisions
6455

65-
---
56+
1. **Fewer tools, richer responses.** 10 tools instead of 50. One search call that aggregates everything.
57+
2. **Local-first.** Embeddings default to a local model (Transformers.js). No cloud, no API key required - but absolutely optional.
58+
3. **Evidence over opinions.** Every signal has a source: adoption %, trend direction, confidence score. No "best practice" claims.
59+
4. **Graceful degradation.** If intelligence isn't available, search still works — just without enrichment. Preflight is additive, not required.
6660

6761
## Sources
6862

69-
### Industry Research
70-
1. [Stack Overflow 2024 Developer Survey](https://survey.stackoverflow.co/2024/ai)
71-
2. [GitClear 2024 AI Code Quality Report](https://www.gitclear.com/) (The "Churn" problem)
72-
3. [DORA State of DevOps 2024](https://dora.dev/research/2024/dora-report/) (Stability vs Throughput)
73-
74-
### Internal Validation
75-
- **Search Contamination**: Without MCP, models copied legacy patterns 40% of the time.
76-
- **Momentum Success**: With "Trending" signals, models adopted modern patterns even when they were the minority (3%).
77-
63+
- [Stack Overflow 2024 Developer Survey](https://survey.stackoverflow.co/2024/ai) — 64.7% cite lack of codebase context as top AI challenge
64+
- [GitClear 2024](https://www.gitclear.com/) — Code churn correlation with AI adoption
65+
- [DORA State of DevOps 2024](https://dora.dev/research/2024/dora-report/) — Throughput vs stability tradeoff

0 commit comments

Comments
 (0)