I built my first task system on markdown files. It worked great. Then I migrated to Jira. That also works great. Here's what I learned about when each approach makes sense.
The File-Based Era
My original setup was simple:
tasks/
├── open/
├── doing/
├── waiting/
├── review/
└── done/
Move a file between directories to change its state. Grep for keywords. Script anything with bash.
Why Files Worked
Zero dependencies. No database to install, no service to run, no API to authenticate. Just a filesystem.
Portable. Sync with Git, Dropbox, rsync. Works on any machine. No vendor lock-in.
Scriptable. Everything is cat, grep, mv, ls. The entire Unix toolchain applies.
Readable. Open any file in any editor. No special client needed. Plaintext forever.
Debuggable. Something wrong? Look at the file. The state is right there.
Where Files Struggled
No real queries. "Show me all tasks tagged 'urgent' created this week" requires building a query engine.
Concurrent access. Two processes moving the same file? Undefined behavior.
Metadata limits. Storing structured data in frontmatter works until it doesn't.
No integrations. Connecting external tools means building custom scripts for everything.
The Jira Era
I switched to Jira when I started running an AI agent that needed to interact with tasks programmatically.
Why Jira Works
Real queries. JQL gives me actual filtering: status = "In Progress" AND created >= -7d.
Structured data. Custom fields, statuses, workflows. First-class support for metadata.
API everything. Every operation is scriptable via CLI or REST.
Integrations. Connect to Slack, GitHub, email. The ecosystem already exists.
Where Jira Struggles
Complexity. Jira is enterprise software. The UI is heavy. Configuration is deep.
Vendor lock-in. Data export exists but isn't trivial. Switching costs are real.
Latency. API calls take time. File operations are instant.
Overkill. For solo work, 90% of Jira's features go unused.
The Decision Framework
Use files when:
- You're the only user
- The data model is simple (key-value or flat documents)
- Portability matters more than features
- You want to avoid dependencies
- Debugging needs to be trivial
Use a database when:
- Multiple users or processes access data concurrently
- You need complex queries or relationships
- External integrations are a priority
- The data model has structure beyond flat documents
- Scale is a concern (thousands+ records)
The Middle Ground
You don't have to choose one forever. My actual setup:
Source of truth: Jira (structured data, queries, integrations) Local cache: JSON files (fast reads, offline access) Sync script: Pulls from Jira, writes local files
Best of both worlds. Jira handles the hard problems. Files give me speed and portability.
What I'd Tell Past Me
Start with files. They're simpler and teach you what you actually need. When you hit real limitations—not imagined ones—then consider alternatives.
The goal isn't to pick the "best" system. It's to pick the system that solves your current problems without creating new ones.
For me, that was files for six months, then Jira when automation requirements grew. Your inflection point will be different.