별고래의 항해일지

Tag: ai-collaboration

  • How to Pick Open-Source Tools by Fit — I Skipped an 84k-Star One

    Summary — the conclusion first

    I weighed four similar tools on GitHub and picked one.

    The interesting part is why I skipped the others. I dropped one with 84k stars, and I trusted a license badge and got it wrong.

    Bottom line: stars are popularity, not fit. And don’t take a badge at face value — I did, and I was wrong.

    Stars are popularity, not “fit”

    Did I pick the one with the most stars? No. I skipped a tool with over 84k stars.

    It was a multi-agent trading framework (TradingAgents, 84k stars). Powerful. But live trading means real money, and it wasn’t what I needed right now.

    A restaurant with 50,000 reviews is like that — not proof it fits my taste. Stars signal “many people look,” not “this fits me.”

    I trusted a badge and got it wrong — the license story

    Here’s where I was wrong. I’ll say it plainly.

    I’d noted one finance terminal (FinceptTerminal) as an “AGPL license trap.” But when I checked, it wasn’t AGPL. It was NOASSERTION — GitHub couldn’t match it to a standard license.

    NOASSERTION doesn’t mean “bad.” It means “the label isn’t standard, so read it yourself.” In fact, Anthropic’s own security tool (defending-harness) was also NOASSERTION.

    Judge by the badge alone and you’ll be wrong. I nearly called a fine project a trap based on the wrapper. A badge is a hypothesis until you read it.

    So the test isn’t “is it good?” but “does it fit?”

    I’m not looking for a good tool. I’m looking for one that fits my stack, my needs, my risk.

    Tool Stars License Why I picked / skipped
    HyperFrames 26k Apache-2.0 ✅ picked — blog to video, used it right away
    TradingAgents 84k Apache-2.0 live-trading risk + not my need now → parked
    FinceptTerminal 26k NOASSERTION read the license yourself + C++ (not my stack) + whole app when I needed parts
    defending-harness 5k NOASSERTION good, but a “customize-it-yourself reference,” not plug-and-play

    They’re all good tools. Just one fit me right now.

    When someone says “they’re all great,” be suspicious

    I first handed this evaluation to an AI assistant. It said all four were great.

    I asked: “You’re saying all four are worth adopting?” Only then did an honest ranking appear.

    Anyone — an AI or a reviewer — leans toward praise when you hand them an evaluation. So change the question. Not “what’s good?” but “what should I drop?”

    One line

    Stars, badges, an AI’s first answer — all just signals. Check it yourself, and pick by “does it fit?” not “is it good?”

    What I checked

    The numbers here aren’t guesses; I confirmed them directly.

    • Stars, license, and language for each repo confirmed via the GitHub API (2026-06)
    • NOASSERTION = GitHub couldn’t identify a standard SPDX license (non-standard/custom) → read the LICENSE file yourself

  • I Built a Blog Publishing Skill — and This Post Is Its First Output

    Summary — the conclusion first

    Publishing one blog post took too many manual steps. Title, summary, category, translation, cache — eleven of them.

    So I built a tool to do it in one shot. The point wasn’t “automation.” It was making the writing actually get read.

    And building it taught me one thing. Building is easy; shipping is hard. This post is my first act of shipping.

    Why I built it — the same eleven chores

    Every time I published, I repeated the same manual steps. I counted eleven.

    1. Write the title
    2. Write the summary
    3. Add a category
    4. Add tags
    5. Post the Korean version
    6. Translate to English
    7. Link the two as a translation pair
    8. Convert to web format
    9. Publish
    10. Purge the cache
    11. Check the URL is alive

    Once is fun. By the tenth time it’s a chore. I’d forget to link the English version, or skip the cache purge and see the old post.

    It’s chopping the same vegetables in the same order every time. You don’t memorize the recipe — you build a meal kit.

    The real problem wasn’t automation — it was “does anyone read it?”

    Automation was half of it. The bigger half was whether the published post actually gets read.

    People don’t read. They scan. Nielsen Norman Group found people read only 20–28% of the words on a page.

    “Made to Stick” has a scarier experiment. People tapping out a song’s rhythm guessed listeners would name it half the time. The real rate was 1 in 40.

    The writer hears the melody; the reader hears only taps. That gap is the “curse of knowledge” — assuming others know what you know.

    So I made readability a “security gate”

    I decided to force readable writing: a checker that blocks publishing if the post fails.

    Think of a password check. Too short, you can’t sign up. Same here — miss the bar, the post doesn’t go up.

    The checks came straight from the research.

    • Is the conclusion at the top — the first sentence of each section is the answer
    • Is any paragraph too long — long ones get skipped
    • Are there enough subheads — signposts for scanners
    • Is any sentence too long — out of breath, can’t read
    • Are there analogies and examples — abstract doesn’t stick

    This post got caught too. My draft ended with a clever little flourish I thought was modest. The checker called it a common cliché. I cut it.

    To me it was style; to the reader, filler. A small case of the curse of knowledge — the checker caught the gap for me.

    An unexpected win — write it well once, gain in three places

    Tidying for readability paid off in more than one place. Three, actually.

    A post that’s easy for humans to scan is easy for search-and-summarize AI to quote. Search now shows AI-assembled answers, and it cites posts with the conclusion up top and short paragraphs first.

    A well-organized post is also easy to share — you can lift the three key lines as they are.

    One lever, three doors: humans, AI, and sharing all point the same way.

    Failure log — raw

    Nothing went smoothly. Here are the snags, as they were.

    The tool rejected my text. One way of moving the text tripped a security filter, so I routed around it.

    It didn’t show in the menu. I built the skill but it wasn’t listed. A single config line at the top of the file was missing. I only found it by comparing with a tool that worked.

    The English URL collided. Using the same address as the Korean version made the system append a number. I gave the English version its own address.

    Behind every clean result there’s this kind of small breakage.

    The stack — infrastructure included

    I won’t hide what runs it.

    The blog runs on one small PC at home. On it, WordPress in Docker, with a multilingual plugin pairing Korean and English.

    External access goes through a Cloudflare tunnel. Drafts are handled by free gpt-4o, and I wrote the readability checker in Python myself.

    What I actually learned — building is easy, shipping is hard

    This is the one thing that stuck. Building a tool is comfortable; shipping is not.

    Building Shipping
    Control in my hands others’ reaction
    If you slip just fix it people see it
    Feeling comfortable uncomfortable
    Growth small large

    So I keep wanting to build more tools. It’s the comfortable side. But growth is on the uncomfortable side.

    So I write this. Not leaving the made thing as-made, but putting it out. This post itself is that practice.

    One line

    I built the tool to force readable writing, but the real lesson was elsewhere: building is easy, shipping is hard — so ship.

    Sources

    • Nielsen Norman Group, “How Users Read on the Web” — only 20–28% of words read
    • Chip & Dan Heath, “Made to Stick” — the curse of knowledge, the tappers experiment
    • Diátaxis — four documentation types (tutorial, how-to, reference, explanation)