The problem: We use AI to refactor legacy code, but regressions sneak through even with tests and type checking. Specs and backlog drift from reality. We needed a way to reverse engineer what the code actually does, then enforce those contracts.
What SpecFact does:
• Analyzes existing Python repos and extracts behavioral contracts (using icontract + beartype)
• Generates machine-readable specs from code (not the other way around)
• Runs as a CI quality gate to block regressions
• Works offline, zero account/API key required
This demo repo shows the full workflow: clone → run `uvx specfact-cli@latest import from-code demo-project --repo .` → see the generated specs and enforcement report.
Key differentiators:
- Brownfield-first: built for legacy code, not greenfield
- No-escape enforcement: quality gates can't be bypassed
- Contract exploration: automatically discovers edge cases with CrossHair
- Watch mode: bidirectional sync between specs and code
Tech stack: Python 3.11+, icontract, beartype, CrossHair for verification, published on PyPI.
The demo takes ~90 seconds to run and produces a concrete analysis report you can inspect. CI example included in .github/workflows/.
I'm around for questions and feedback. What would make this more useful for your brownfield projects?
Hey HN! I'm the creator of SpecFact CLI.
The problem: We use AI to refactor legacy code, but regressions sneak through even with tests and type checking. Specs and backlog drift from reality. We needed a way to reverse engineer what the code actually does, then enforce those contracts.
What SpecFact does: • Analyzes existing Python repos and extracts behavioral contracts (using icontract + beartype) • Generates machine-readable specs from code (not the other way around) • Runs as a CI quality gate to block regressions • Works offline, zero account/API key required
This demo repo shows the full workflow: clone → run `uvx specfact-cli@latest import from-code demo-project --repo .` → see the generated specs and enforcement report.
Key differentiators: - Brownfield-first: built for legacy code, not greenfield - No-escape enforcement: quality gates can't be bypassed - Contract exploration: automatically discovers edge cases with CrossHair - Watch mode: bidirectional sync between specs and code
Tech stack: Python 3.11+, icontract, beartype, CrossHair for verification, published on PyPI.
The demo takes ~90 seconds to run and produces a concrete analysis report you can inspect. CI example included in .github/workflows/.
I'm around for questions and feedback. What would make this more useful for your brownfield projects?
Docs: https://docs.specfact.io PyPI: https://pypi.org/project/specfact-cli/