====== Source-Driven Development vs Assumption-Driven Development ======
**Source-Driven Development** and **Assumption-Driven Development** represent two contrasting methodologies for AI agents and software engineers when making framework decisions, managing dependencies, and resolving technical ambiguities. Source-Driven Development prioritizes grounding decisions in official documentation and verified sources, while Assumption-Driven Development relies on pattern matching and inferred conventions. This distinction has significant implications for system reliability, maintainability, and the detection of compatibility issues in complex software projects.

===== Conceptual Foundations =====
The fundamental difference between these approaches lies in how decisions are justified and validated. Source-Driven Development requires that framework choices, configuration decisions, and architectural patterns be explicitly documented with citations to official sources—whether these are framework documentation, API specifications, published standards, or official implementation guides (([[https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - Source-Driven Development vs Assumption-Driven Development (2026]])). This methodology enforces a discipline where agents or developers cannot justify a decision purely through inference or pattern recognition.

Assumption-Driven Development, by contrast, operates through **pattern matching and heuristic reasoning**. In this approach, agents or developers observe common patterns in codebases, infer conventions from similar projects, and make educated guesses about best practices without requiring explicit verification against official guidance. While this approach can be faster in familiar domains, it introduces systematic risks when versions change, APIs evolve, or subtle compatibility issues exist between dependencies.

===== Implementation Characteristics =====
**Source-Driven Development** implementations emphasize explicit citation trails and traceability. When an AI agent makes a framework decision using this methodology, the decision includes references to the specific version of documentation that justified the choice. For instance, rather than assuming a Django ORM pattern applies universally, a source-driven approach would cite the specific Django version documentation and note any version-specific behavior. This creates an auditable record that becomes valuable when versions are upgraded or when debugging unexpected behavior.

The practical workflow in source-driven development includes several key steps: (1) identifying the decision point or technical question, (2) consulting official documentation or specifications, (3) documenting the specific source consulted, (4) implementing based on verified guidance, and (5) recording the citation for future reference. This overhead becomes particularly valuable when managing complex dependency chains or when multiple framework versions coexist in an organization.

Assumption-Driven Development relies on faster decision-making through accumulated pattern recognition. Developers or agents apply heuristics learned from previous projects, common architectural patterns in the ecosystem, and tacit knowledge about framework behavior. While this approach accelerates initial development and works well in stable, well-documented domains, it becomes problematic when encountering:

* **Version mismatches** between dependencies that behave differently across releases
* **Undocumented behavior changes** in framework updates
* **Non-standard implementations** that deviate from documented patterns
* **Edge cases** not covered by common patterns
* **Subtle compatibility issues** between transitive dependencies

===== Comparative Advantages and Limitations =====
Source-Driven Development demonstrates particular strengths in environments requiring high reliability, long-term maintainability, and clear accountability. The explicit citation requirements catch version mismatches early because decisions are pinned to specific documentation versions (([[https://alphasignalai.substack.com/p/how-ai-agents-follow-senior-engineer|AlphaSignal - Source-Driven Development vs Assumption-Driven Development (2026]])).  When a framework update occurs, the sourced decision becomes outdated in a detectable way, triggering review and potential adjustment. This methodology scales well across large teams and long project timelines, where tacit knowledge becomes unavailable and institutional memory is unreliable.

The primary limitation of source-driven approaches is velocity. Requiring explicit documentation lookup and citation for each significant decision slows development, particularly in domains where conventions are stable and well-known. Additionally, this methodology depends on documentation quality; when official sources are incomplete, outdated, or ambiguous, the enforcement of source-driven decision-making becomes problematic.

Assumption-Driven Development excels in exploratory phases, rapid prototyping, and domains with mature, stable conventions. Pattern matching against established ecosystem norms accelerates decision-making and allows developers to leverage tacit knowledge effectively. This approach works particularly well in teams with high experience levels and strong shared mental models about framework behavior.

However, assumption-driven approaches accumulate technical debt through implicit dependencies on specific framework versions, undocumented conventions, and fragile pattern matches. When versions change, new team members arrive without the tacit knowledge, or unusual requirements emerge that don't match common patterns, assumption-driven systems become expensive to maintain and risky to modify.

===== Applications in AI Agent Development =====
The source-driven versus assumption-driven distinction becomes particularly acute in AI agent development, where agents must make autonomous decisions about framework selection, dependency management, and architectural patterns. Agents trained with source-driven methodologies develop behavior aligned with explicit verification—consulting documentation before making decisions, citing sources for recommendations, and detecting version incompatibilities through documentation analysis rather than runtime failures.

Agents employing assumption-driven approaches can make faster initial decisions but are more prone to deploying systems with latent compatibility issues. These agents recognize patterns suggestive of particular framework versions or architectural approaches but cannot validate their assumptions against current official specifications.

===== Current Status and Best Practices =====
Industry practice increasingly favors **hybrid approaches** that combine elements of both methodologies. Development teams maintain documented decision records that cite official sources while allowing assumption-driven rapid decisions in well-established, version-stable domains. This hybrid model preserves the speed benefits of pattern matching while maintaining the reliability guarantees of source verification for critical decisions, particularly those affecting system architecture, security, or cross-component compatibility.

For AI agents specifically, contemporary best practices emphasize training agents to distinguish between decisions that require source verification and those that can safely rely on established patterns. This distinction allows agents to operate efficiently in routine decisions while ensuring that framework choices, dependency selections, and architectural patterns are grounded in official documentation.


===== See Also =====
  * [[source_driven_development_skill|Source-Driven Development Skill]]
  * [[ai_generated_vs_careful_codebases|AI-Generated vs Carefully-Crafted Codebases]]
  * [[doubt_driven_development_skill|Doubt-Driven Development (Adversarial Fresh-Context Review)]]
  * [[agentic_scaffolding|Agentic Scaffolding]]
  * [[salesforce_vs_agent_platforms|Salesforce vs Emerging Agent Platforms]]

===== References =====