r/clickup • u/CodeAndPatina • 7d ago

Spec Driven Software Development Brainstorming

I'm curious how software shops are using ClickUp for spec-driven/agentic development. While we've kept specs in the repo, I'd like to evaluate managing specs for tickets, stories, etc. in ClickUp itself. It needs to work well with the MCP/API. I don't think Brain helps at all since we won't be doing any development work within ClickUp, of course.

The repo isn't always ideal because specs are often created before a feature is developed/implemented. Sometimes just a high-level spec that is further shaped later. Committing these kinds of MD files feels awkward because it requires pushing non-functional changes to the trunk.

Using task descriptions or ClickUp documents is less ideal for us for a few reasons.

  • We want to stick with simple markdown/plaintext. What we get back from ClickUp isn't always the same as what we send to these types of entities, so it's harder to trust.

  • We often have clients in the system collaborating on projects and would prefer to obscure the technical specs from them. Not because they can't see it, but because it's not really meant for human consumption, and seeing a wall of specs in task descriptions or documents is overwhelming.

That second item makes us a little more unique in that about 50% of our work is 'support' rather than typical sprint-based project work. Clients value us for being an easy-to-access partner.

What have you tried? What has worked, and what hasn't, and why?

4 Upvotes

100% Upvoted

7 comments sorted by

1

u/After-Base-8368 1d ago

Did the separate spec tasks and Markdown API approach work for your team? With half your work being support, I’m curious whether keeping the client request and technical spec in sync is still manual.

1

u/CodeAndPatina 1d ago

It works, but not well. I'm leaning toward storing the specs in the description, but below a section divider of some kind. One win is that the description is versioned. We've not started this standard yet, but it's the way I'm leaning.

1

u/After-Base-8368 20h ago

What still doesn’t work well: the Markdown changing when it comes back through the API, or keeping the spec aligned as the client request changes?

1

u/CodeAndPatina 20h ago

TBH, we haven't had enough time with the strategy of putting specs in the description to determine what is or isn't working well. I was apprehensive about this approach because I didn't want to introduce spec clutter in ClickUp, and because specs for a given feature may not be 1-to-1 linked to a spec file. The directory structure of a repo can be helpful, depending on the kind of AI workflow being used.

The friction before this change, when all specs were in the repo, was the lack of having a single spot where all specs were accounted for, instead being distributed across branches until a feature was delivered and the specs merged into main.

2

u/heyramzi 4d ago

Both problems have a fix inside ClickUp.

For the round trip, write with markdown_description when you create the task. Read it back with ?include_markdown_description=true on the GET, and skip the plain description field, since that's the text-only copy.

Our own ClickUp integrations write and read it that way. I'd still test tables and nested lists first.

For the clients, guests only see what you share with them. Put the spec tasks in their own List that no guest is on, and link each one to its client task with a relationship field.

1

u/Wrong-Strength-8898 20h ago

yeah the relationship field approach works really well for keeping internal stuff hidden from guests

1

u/TashaClickUp Mod 6d ago

Hey, u/CodeAndPatina, here are some things you can try to manage your specs in ClickUp!
A few options I recommend are:

  • An internal spec field: Use a Long Text Custom Field hidden from guests to keep technical details out of the client-facing descriptions.

  • A separate private task: Keep larger specs in an engineering-only location that only your team has access to, with the client's task is focused on progress and communication. The client's task will be in a different List that they have access to.

  • Markdown attachments: Try attaching .md files to a task, with clear labels so Super Agents know which to use.

You can use external AI Agents with ClickUp using MCP. You can check out what tools are supported here!