{"slug": "your-code-knows-what-changed-but-does-it-know-why", "title": "Your Code Knows What Changed. But Does It Know Why?", "summary": "A developer argues that AI-assisted software engineering faces a growing challenge: while writing code is becoming cheaper, understanding why code exists is not. The developer proposes an 'Engineering Graph' that connects pull requests, commits, files, services, deployments, incidents, fixes, and engineers to reveal the rationale behind code changes, helping engineers avoid breaking production systems.", "body_md": "**AI can write a pull request in seconds.**\n\nBut when that pull request touches a piece of code written three years ago, there is a much harder question:\n\nWhy does this code exist?\n\nThat answer might be buried across 47 commits, 12 pull requests, an old incident, a Slack conversation nobody remembers, and one engineer who left the company six months ago.\n\nThis is becoming one of the biggest problems in AI-assisted software engineering.\n\nBecause **writing code is getting cheaper. Understanding code is not.**\n\nConsider this:\n\n```\nif (user.isLegacy && !featureEnabled) {\n  return fallback();\n}\n```\n\nLooks suspicious.\n\nMaybe it's dead code.\n\nMaybe someone forgot to clean it up.\n\nSo an AI coding agent suggests:\n\n```\n- if (user.isLegacy && !featureEnabled) {\n-   return fallback();\n- }\n```\n\nThe tests pass.\n\nThe PR looks clean.\n\nYou merge it.\n\nThree hours later, production breaks for a subset of customers.\n\nNow you're asking a very different question:\n\nWho knew why that code was there?\n\nThe answer might have been hiding in the engineering history.\n\nGit is incredible.\n\nIt can tell you:\n\n```\nWhat changed?\nWho changed it?\nWhen did they change it?\n```\n\nBut those aren't always the questions engineers need answered.\n\nWe need:\n\n```\nWhy did it change?\n\nWhat problem was it solving?\n\nWhat depends on it?\n\nWhat happens if I change it?\n\nHas this failed before?\n\nWho understands this part of the system?\n\nWas this introduced because of an incident?\n\nWhat happened the last time someone touched it?\n```\n\nThe problem isn't that this information doesn't exist.\n\n**It does.**\n\nIt's just fragmented.\n\nEvery engineering organization already has a graph.\n\nThey just don't usually call it one.\n\nA pull request is connected to commits.\n\nCommits are connected to files.\n\nFiles are connected to services.\n\nServices are connected to deployments.\n\nDeployments are connected to incidents.\n\nIncidents are connected to fixes.\n\nFixes are connected to engineers.\n\nEngineers are connected to decisions.\n\nDecisions are connected to outcomes.\n\nLike this:\n\n```\n                    ┌────────────┐\n                    │   Issue    │\n                    └─────┬──────┘\n                          │\n                       solved by\n                          │\n                          ▼\n                    ┌────────────┐\n                    │     PR     │\n                    └─────┬──────┘\n                          │\n                       modified\n                          │\n                          ▼\n                    ┌────────────┐\n                    │    Code    │\n                    └─────┬──────┘\n                          │\n                      depends on\n                          │\n                          ▼\n                    ┌────────────┐\n                    │  Service   │\n                    └─────┬──────┘\n                          │\n                      affected\n                          │\n                          ▼\n                    ┌────────────┐\n                    │  Incident  │\n                    └─────┬──────┘\n                          │\n                       caused\n                          │\n                          ▼\n                    ┌────────────┐\n                    │    Fix     │\n                    └────────────┘\n```\n\nThe valuable information isn't just the nodes.\n\n**It's the edges.**\n\nSuppose you're looking at:\n\n```\ncheckout.ts\n```\n\nA traditional code search might tell you:\n\n```\ncheckout.ts\n├── imported by payment.ts\n├── imported by cart.ts\n└── imported by order.ts\n```\n\nUseful.\n\nBut an Engineering Graph could tell you:\n\n```\ncheckout.ts\n│\n├── modified by PR #842\n│     ├── solved issue #421\n│     ├── reviewed by Maya\n│     └── followed incident #91\n│\n├── depends on retry.ts\n│     └── introduced after checkout timeout\n│\n├── affects payment-service\n│\n└── changed 7 times during payment incidents\n```\n\nNow you aren't just looking at code.\n\nYou're looking at **the story of the code**.\n\nAnd that story can change the decision you make.\n\nThis is where things get interesting.\n\nImagine asking an AI agent:\n\n\"Can I remove this retry?\"\n\nWith only the source code, it might respond:\n\n\"The retry appears redundant and could potentially be removed.\"\n\nThat's not useful.\n\nNow give it the engineering context:\n\n```\nretry.ts\n   ↓\nused by checkout.ts\n   ↓\nintroduced in PR #842\n   ↓\nPR linked to checkout timeout #421\n   ↓\nincident #91 involved the same request path\n   ↓\nthree subsequent PRs modified retry behavior\n```\n\nNow the answer could be:\n\n\"I would not remove it yet. This retry mechanism was introduced to address a checkout timeout and has been modified several times after production issues. I'd inspect incident #91 and the related PRs before changing it.\"\n\nSame model.\n\nDifferent context.\n\n**Better context → better reasoning.**\n\nThat's the fundamental idea.\n\nYou don't need a giant infrastructure project to understand the architecture.\n\nStart with a tiny graph.\n\n```\ntype NodeType =\n  | \"file\"\n  | \"commit\"\n  | \"pull_request\"\n  | \"issue\"\n  | \"service\"\n  | \"incident\"\n  | \"person\";\n\ntype Relationship =\n  | \"MODIFIED\"\n  | \"SOLVED\"\n  | \"DEPENDS_ON\"\n  | \"AUTHORED_BY\"\n  | \"REVIEWED_BY\"\n  | \"AFFECTED\"\n  | \"CAUSED\";\n```\n\nOur nodes:\n\n```\ntype Node = {\n  id: string;\n  type: NodeType;\n  name: string;\n  metadata?: Record<string, unknown>;\n};\n```\n\nAnd edges:\n\n```\ntype Edge = {\n  from: string;\n  to: string;\n  relationship: Relationship;\n  metadata?: Record<string, unknown>;\n};\n```\n\nNow we can represent:\n\n``` js\nconst edges: Edge[] = [\n  {\n    from: \"pr:842\",\n    to: \"file:checkout.ts\",\n    relationship: \"MODIFIED\",\n  },\n  {\n    from: \"pr:842\",\n    to: \"issue:421\",\n    relationship: \"SOLVED\",\n  },\n  {\n    from: \"file:checkout.ts\",\n    to: \"file:retry.ts\",\n    relationship: \"DEPENDS_ON\",\n  },\n  {\n    from: \"incident:91\",\n    to: \"service:checkout\",\n    relationship: \"AFFECTED\",\n  },\n];\n```\n\nThat's already enough to start answering questions that plain text search struggles with.\n\nNow put an AI agent on top.\n\nA traditional agent looks something like:\n\n```\nGoal\n ↓\nObserve\n ↓\nDecide\n ↓\nAct\n ↓\nCheck\n ↓\nRepeat\n```\n\nUseful.\n\nBut it starts every task with roughly the same level of ignorance.\n\nGive it the graph:\n\n```\n                    ┌──────────────────────┐\n                    │        Goal          │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │    Query Graph       │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │      Observe         │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │       Decide         │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │       Execute        │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │       Verify         │\n                    └──────────┬───────────┘\n                               ↓\n                    ┌──────────────────────┐\n                    │    Update Graph      │\n                    └──────────┬───────────┘\n                               │\n                               └──────→ Next task\n```\n\nNow the agent doesn't just observe the repository.\n\n**It observes what happened before.**\n\nThis distinction is easy to miss.\n\nWe normally think an AI system improves like this:\n\n```\nBetter model\n     ↓\nMore training\n     ↓\nBetter weights\n     ↓\nBetter performance\n```\n\nBut agents have another path:\n\n```\nBetter experience\n       ↓\nBetter graph\n       ↓\nBetter context\n       ↓\nBetter decisions\n       ↓\nBetter experience\n```\n\nThe underlying model doesn't have to change.\n\nThe **environment around the model** improves.\n\nThat's powerful.\n\nWe shouldn't blindly turn agent activity into permanent knowledge.\n\nImagine an agent tries:\n\n```\nIncrease retry count: 2 → 10\n```\n\nThe test passes.\n\nThe agent records:\n\n```\n\"10 retries fixes checkout.\"\n```\n\nNext week another agent sees that \"knowledge\" and does the same thing.\n\nNow you've created a feedback loop that makes the system **confidently worse**.\n\nThat's why learning systems need evidence.\n\nInstead of:\n\n```\nAgent says it worked.\n```\n\nStore:\n\n```\nCode changed\n    ↓\nUnit tests passed\n    ↓\nIntegration tests passed\n    ↓\nPR merged\n    ↓\nDeployment succeeded\n    ↓\nNo incident followed\n```\n\nNow your graph can represent:\n\n```\ntype Outcome = {\n  status: \"success\" | \"failure\";\n  confidence: number;\n  evidence: string[];\n};\n```\n\nFor example:\n\n``` js\nconst outcome: Outcome = {\n  status: \"success\",\n  confidence: 0.92,\n  evidence: [\n    \"unit tests passed\",\n    \"integration tests passed\",\n    \"pull request merged\",\n    \"deployment succeeded\",\n  ],\n};\n```\n\nThe system isn't just remembering.\n\nIt's remembering **why it believes something**.\n\nThat difference becomes enormous at scale.\n\nAn agent might make 50 observations while solving one problem.\n\nWe shouldn't permanently promote all 50 into \"truth.\"\n\nThere are levels:\n\n```\nObservation\n     ↓\nEvidence\n     ↓\nRepeated pattern\n     ↓\nValidated relationship\n     ↓\nReusable knowledge\n     ↓\nHeuristic\n```\n\nFor example:\n\n```\ncheckout.ts imports retry.ts\nPR #842 modified checkout.ts\nTests passed after the change.\ncheckout.ts frequently changes with retry.ts.\nWhen checkout timeout tests fail,\ninspect retry behavior first.\n```\n\nThat's a much safer learning architecture than dumping every agent thought into a vector database.\n\nThis might be the most underrated part.\n\nSuppose an agent tries two approaches:\n\n```\nTask: Fix checkout timeout\n\nApproach A\n    ↓\nFAILED\n\nApproach B\n    ↓\nSUCCEEDED\n```\n\nA normal system might only remember B.\n\nA learning system should remember **both**.\n\n```\nTask\n│\n├── attempted → Approach A\n│                 └── FAILED\n│\n└── attempted → Approach B\n                  └── SUCCEEDED\n```\n\nThat's negative knowledge.\n\nThe next agent doesn't have to walk into the same wall.\n\nIt can know:\n\n\"This approach was already tried. It failed.\"\n\n**The graph remembers the dead ends.**\n\nRAG is incredibly useful.\n\nBut RAG and an Engineering Graph solve different problems.\n\nRAG asks:\n\nWhat information is relevant to this question?\n\nA graph can ask:\n\nHow are these things related?\n\nImagine asking:\n\n```\nWhy is checkout.ts high risk?\n```\n\nA document retriever might find:\n\n```\nPR #842\nPR #811\nPR #743\n```\n\nA graph can reconstruct:\n\n```\ncheckout.ts\n│\n├── modified by PR #842\n│      ├── authored by Maya\n│      └── reviewed by Bobby\n│\n├── related to retry.ts\n│\n├── affected checkout-service\n│\n└── connected to incident #91\n       └── caused by previous checkout change\n```\n\nThat's not just retrieval.\n\nThat's **contextual reasoning over relationships**.\n\nAnd the two technologies work beautifully together:\n\n```\n                 User Question\n                       ↓\n              ┌────────────────┐\n              │  Semantic Search│\n              └───────┬────────┘\n                      ↓\n              Relevant entities\n                      ↓\n              ┌────────────────┐\n              │ Graph Traversal│\n              └───────┬────────┘\n                      ↓\n               Relationships\n                      ↓\n              ┌────────────────┐\n              │      LLM       │\n              └───────┬────────┘\n                      ↓\n             Evidence-backed answer\n```\n\nThis is where the idea gets really interesting.\n\nImagine your engineering graph continuously absorbs:\n\n```\nGitHub\n   ↓\nCommits\n   ↓\nPull Requests\n   ↓\nCode\n   ↓\nServices\n   ↓\nDeployments\n   ↓\nIncidents\n   ↓\nFixes\n   ↓\nAgent Experiences\n```\n\nThen add:\n\n```\nJira\nSlack\nConfluence\nDatadog\nArchitecture decisions\nHuman feedback\n```\n\nEventually you're not building another code search engine.\n\nYou're building a **living model of how the engineering organization works**.\n\nYou can ask:\n\n```\nWhy was this architecture chosen?\n\nWho understands this service?\n\nWhat usually breaks when we change it?\n\nWhich files are high risk?\n\nWhat has already been tried?\n\nWhich engineers solved similar problems?\n\nWhat happened after the last deployment?\n\nWhat should an AI agent inspect before touching this service?\n```\n\nThose answers don't exist in any single system.\n\nThey emerge from the **connections between systems**.\n\nHere's the part I think matters most.\n\nAI is making software creation dramatically faster.\n\nThat's great.\n\nBut it creates a new bottleneck:\n\n**understanding.**\n\nIf AI can generate 10x more code, we need tools that help engineers understand 10x more software.\n\nOtherwise we're just accelerating the production of systems nobody fully understands.\n\nThe next generation of engineering tools won't just answer:\n\n\"What does this code do?\"\n\nThey'll answer:\n\n\"Why is it here, what does it connect to, what happened before, and what happens if I change it?\"\n\nThat's a much harder problem.\n\nAnd a much more valuable one.\n\nI think the architecture eventually becomes surprisingly simple:\n\n```\n┌─────────────────────────────────────┐\n│               AGENTS                │\n│        Reason • Plan • Act          │\n└──────────────────┬──────────────────┘\n                   │\n                   ▼\n┌─────────────────────────────────────┐\n│              CONTEXT                │\n│       Search • Retrieval • RAG       │\n└──────────────────┬──────────────────┘\n                   │\n                   ▼\n┌─────────────────────────────────────┐\n│        ENGINEERING GRAPH             │\n│ Code • PRs • People • Incidents     │\n│ Decisions • Dependencies • Outcomes │\n└──────────────────┬──────────────────┘\n                   │\n                   ▼\n┌─────────────────────────────────────┐\n│              EVIDENCE               │\n│     GitHub • CI • Deployments       │\n│      Observability • Humans         │\n└─────────────────────────────────────┘\n```\n\n**The model provides reasoning.**\n\n**The tools provide action.**\n\n**The graph provides memory.**\n\n**Evidence provides trust.**\n\nPut those together and you get something much more interesting than an AI coding assistant.\n\nYou get an engineering system that can **learn from the work it performs.**\n\nThe future of AI-assisted engineering isn't just about generating code faster.\n\nIt's about building systems that understand the software they're changing.\n\nEvery commit tells a story.\n\nEvery pull request adds context.\n\nEvery incident teaches something.\n\nEvery fix creates new knowledge.\n\nEvery engineer leaves behind experience.\n\nThe opportunity is to connect all of it.\n\nBecause your code already knows **what changed**.\n\nYour Git history knows **when**.\n\nYour team knows **why**.\n\nThe problem is that nobody has connected the three.\n\n**That's what Engineering Intelligence should do.**\n\nAnd that's what we're building with **Helix**: a living engineering graph that connects software, engineering activity, decisions, and evidence so humans and AI can understand what happened before deciding what happens next.\n\nThe goal isn't AI that confidently guesses.\n\nThe goal is AI that can **show its work**.\n\n**Connect your GitHub and see what your code knows.**", "url": "https://wpnews.pro/news/your-code-knows-what-changed-but-does-it-know-why", "canonical_source": "https://dev.to/bobbyhalljr/your-code-knows-what-changed-but-does-it-know-why-3mi0", "published_at": "2026-08-30 13:38:31+00:00", "updated_at": "2026-08-30 13:53:26.011610+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-products", "artificial-intelligence"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/your-code-knows-what-changed-but-does-it-know-why", "markdown": "https://wpnews.pro/news/your-code-knows-what-changed-but-does-it-know-why.md", "text": "https://wpnews.pro/news/your-code-knows-what-changed-but-does-it-know-why.txt", "jsonld": "https://wpnews.pro/news/your-code-knows-what-changed-but-does-it-know-why.jsonld"}}