Policy: Chat Formatting

O Claude Code renderiza respostas em *ommonMark*(Github-flavored markdown) com fonte monoespaçada. O usuário interage com o texto renderizado, não com o que a IA "escreve". Toda decisão de formatação deve favorecer a interação direta: clicar no link abre o browser, copiar o comando funciona com triple-click, etc.

1. URLs

Regra base

*empre*envolver URLs em sintaxe que o renderizador transforme em link clicável. Há duas formas válidas:

• *arkdown link*— [texto descritivo](https://hub.koder.dev/apps/koder-cal)

  quando o texto agrega contexto. *adrão preferido*quando o link está no meio de uma frase.

• *utolink*— <https://hub.koder.dev/apps/koder-cal> quando a URL

  é o próprio conteúdo. Útil em listas / tabelas onde o texto seria redundante.

Anti-padrão

Nunca escrever URLs cruas:

❌ Acesse https://hub.koder.dev/foo para ver
✅ Acesse [hub.koder.dev/foo](https://hub.koder.dev/foo) para ver
✅ Acesse <https://hub.koder.dev/foo> para ver

URLs cruas são copiáveis (com seleção manual) mas *ão clicáveis*— quebram o fluxo do usuário e atrapalham especialmente em chats longos onde o usuário escaneia visualmente.

Casos comuns

URLs em listas e tabelas

• Em *abelas* preferir autolink curto: | status | <https://...> |

  para não quebrar alinhamento.

• Em *istas com descrição* Markdown link é mais legível:

  - [Hub admin dashboard](https://hub.koder.dev/admin) — gestão de pacotes

URLs com fragmentos / queries

Manter intactos no link. O renderizador encoda automaticamente:

✅ [hub.koder.dev/apps/cal#screenshots](https://hub.koder.dev/apps/cal#screenshots)
✅ <https://flow.koder.dev/Koder/koder/issues?type=all&state=open>

URLs internas (path-only)

Para paths dentro do monorepo, *ÃO*usar URL — o renderizador do Claude Code linka paths automaticamente para abrir no editor. Manter o formato path/to/file.dart:LINE:

✅ Veja `products/dev/hub/app/lib/main.dart:120`
❌ Veja [main.dart](products/dev/hub/app/lib/main.dart)

2. Comandos copiáveis

Comandos shell que o usuário pode querer rodar devem aparecer em *loco de código separado*(não inline) para ter o ícone "Copy" do renderizador:

✅

git tag devhubv2.29.99 git push origin devhubv2.29.99

❌ Rode `git tag dev/hub/v2.29.99 && git push origin dev/hub/v2.29.99`
   no terminal

Inline code ainda é OK quando referencia um símbolo, não um comando para copiar (ex.: "a função packageShareUrl retorna...").

3. Paths e símbolos

• *ath com linha* path/to/file.dart:42 — ativa "go to line" do editor
• *ath sem linha* path/to/file.dart (em backticks) — abre o arquivo
• *ímbolo* nomeDaFunção (em backticks) — destaca, não vira link
• *epositório* Koder/koder (em backticks) — não vira link sozinho

4. Quando autolink *ão*é suficiente

Se o renderizador-alvo não suporta autolinks (<url>), Markdown link explícito é mais compatível. *ommonMark*(Claude Code, GitHub, Discord, Slack) suporta ambas formas. Quando em dúvida, use Markdown link [text](url).

5. URLs de produtos Koder

URLs canônicas dos produtos Koder seguem o padrão <produto>.koder.dev (per specs/landing-pages/products.kmd §URL). *unca*linkar para app.<produto>.koder.dev ou variantes não-canônicas — quebra a expectativa do usuário e pode levar a 404.

✅ [hub.koder.dev](https://hub.koder.dev)
✅ [id.koder.dev/auth/callback](https://id.koder.dev/auth/callback)
❌ [app.hub.koder.dev](https://app.hub.koder.dev)

6. Não-objetivos

Esta policy *ão cobre*

• Formatação dentro de *rquivos commitados*(READMEs, RFCs, etc.) —

  cabe à spec de cada tipo de documento (specs/readmes/products.kmd, specs/docs/generation.kmd).

• Formatação em commits Git — cabe à convenção do CLAUDE.md

  ("commit message style").

• Output programático em CLI ou logs — formatação JSON / TSV é

  separada (não envolve renderizador interativo).

Esta policy é só sobre *hat ao vivo com o usuário*