Welcome to learn-spec-driven-dev!

[leo-sigales]

Welcome to learn-spec-driven-dev

Welcome to the first educational repository in the Syntran Labs Learning Lab collection.

This project is a hands-on learning example for Spec-Driven Development: a way of building software where requirements, specifications, tests, implementation, and documentation stay connected from the beginning.

The goal is not only to write code.

The goal is to show how a small software project can be built in a way that is:

• understandable
• testable
• documented
• extensible
• reviewable by humans
• compatible with responsible AI-assisted development

What this project is

learn-spec-driven-dev is an educational Python project that demonstrates how to move from an idea to working software through a structured workflow:

1. Define the expected behavior.
2. Write clear specifications.
3. Turn specifications into executable tests.
4. Implement the smallest useful version.
5. Refactor without changing behavior.
6. Document the architecture and decisions.
7. Make the project easy for others to understand and extend.

The current example uses a simple price-fetching domain because it is easy to understand, but the real subject is the engineering workflow.

What this project is not

This is not intended to be a production-grade financial API.

It is not financial advice.

It is not a trading tool.

It is not a showcase of “AI-generated code” for its own sake.

The purpose is educational: to demonstrate how software can be developed with structure, traceability, tests, and documentation, including when AI tools are used as part of the workflow.

Why this exists

AI-assisted coding is becoming faster and more accessible.

That is powerful, but speed alone does not create good software.

A generated codebase can still be hard to review, hard to test, hard to maintain, or hard to trust.

This project exists to explore a different approach:

AI can help accelerate development, but engineering discipline still matters.

Specifications, tests, documentation, review, and clear architecture are what make the output useful.

Who this is for

This repository may be useful for:

• developers learning Python project structure
• people interested in TDD or Spec-Driven Development
• engineers exploring AI-assisted coding workflows
• students learning how to connect requirements to tests
• technical leads thinking about reviewable AI-generated work
• contributors who want to improve educational software examples

You do not need to be an expert to participate.

Questions, feedback, corrections, documentation improvements, and small contributions are welcome.

Good ways to contribute

You can help by:

• reading the README and telling us what is unclear
• opening issues for confusing instructions or broken setup steps
• improving documentation
• adding beginner-friendly explanations
• adding new test cases
• proposing new specifications
• adding new educational examples
• improving the architecture diagram or developer guide
• sharing how you would teach this workflow to someone else

If you are new to open source, documentation and setup feedback are especially valuable.

Discussion guidelines

Please keep discussions constructive and practical.

Good discussion topics include:

• questions about the Spec-Driven Development workflow
• suggestions to improve the learning experience
• ideas for future examples
• feedback on the README or documentation
• ways to make the project easier for beginners
• comparisons with TDD, BDD, OpenSpec, or other structured development approaches
• responsible use of AI tools in software engineering

Please avoid using Discussions for unrelated promotion, generic AI hype, or financial/trading conversations. The price-fetching domain is only an example.

Suggested first questions

If you are visiting for the first time, feel free to reply with one of these:

• What part of the project was easiest to understand?
• What part was confusing?
• Would this help someone learn Spec-Driven Development?
• What example should be added next?
• What would make this easier for a first-time contributor?
• How do you personally use specs, tests, or AI tools in your workflow?

Next step

Start by reading the README, running the tests, and exploring the documentation.

Then feel free to open an issue, start a discussion, or suggest a small improvement.

This is early by design.

The goal is to build the learning path in public, with feedback from people who care about better software engineering.

[leo-sigales]

Personal note

I’m building this project as part of a broader effort to explore how AI-assisted development can become more structured, reviewable, and useful in real engineering contexts.
My goal is not to present this as a perfect project. The goal is to make the process visible and improve it with feedback.
If something is unclear, incomplete, too advanced, or too simple, that feedback is welcome.