Comment by amluto | Hacker News Reader

Comment by amluto | Hacker News Reader

Parent Full thread

I skimmed a couple pages of the docs at:

https://github.com/user-attachments/files/31802150/EXTERNAL....

Might I gently suggest that you have a model at least as capable as Opus 5.5 translate that from Claudish to English? Or, even better, have an actual human work on the docs a bit? As it stands, they are fairly egregious, and they seem to devote at least as much space to little AI-generated quips that convey no meaning than to actually explaining what’s going on.

Also, maybe a human should decide whether these are “function” hooks or “module” hooks. All of this marketing calls them “function” hooks, but the json config seems entirely unaware of this.

(Has anyone else noticed that half the sentences in Claudish aren’t merely weird: they are noun phrases and not sentences at all? I’m pretty sure that any decent pre-LLM NLP-based grammar checker would correctly flag half the sentences in Claudish. Also, whatever variant of Claude wrote this thing can’t even capitalize around semicolons consistently with itself, let alone consistently with how English has been written for at least a century.)

edit: Fixed the link. Thanks, kaszanka.

Ouch! Much of this verbiage was dictated by me personally; I just have a fairly distinct register some might consider inscrutable. My English teachers in grade school always said the same :)

Rest assured I'll inject a bit less soul into the official docs once Mods are launched; re your feedback on the JSON key, what would you recommend?

Your comment here is written in perfectly fine English :)

Maybe "function_hook_modules" for the JSON key?

Does this finally fix the limitation that there is no supportable way to replace the implementation of a native tool in Claude Code? codex-rs has an (undocumented but likely supportable if kind of awkward) mechanism, and I’m part way through a project that needs this. I was going to release it with a recommendation not to use Claude Code, but it’s at least plausible that this will change my mind. (I’m not sure yet — the $ mechanism might be too restrictive. It’s a start at least.)

Having given the JSON more than two seconds of thought, I have a very different suggestion:

    {
     "function_hooks": {
      "version": 1,
      "source_file": "./whatever.ts",
      "language": "TypeScript",
      "hash": "sha256:abcd..."
     }
    }

Don't trust my formatting -- I typed this in the comment box and I have not run it through a prettifier or anything.

The point here is that there's a world adjacent to but not actually contained within Claude Code in which not everything blindly trusts everything else, and maybe it's time to start remembering some lessons from the 90's on. For example:

- Don't sniff content types and preferably don't infer them from filenames either.

- Don't trust your subresource to arrive intact. Pin those hashes and verify them!

- Leave some room for extensibility.

- Maybe don't require everyone to mix their code with the security policy that controls edits to that code? I realize that anyone cursed with GitHub Actions is forced to violate this rule in the most outrageous ways imaginable, but that doesn't mean that Claude Code needs to follow suit forever. Once there's subresource integrity, the actual subresource can be put somewhere else where it belongs better. If there's "source_file", in the future there can be "source_url" and such without trying to infer it from the formatting of the string.

(I've involved absolutely no AI in the preparation of this comment. I make plenty of use of AI, but I like my brain to stay exercised, and I like to think that I remain MUCH better at this kind of thing than even the best current models.)

For someone so pedantic, your writing is remarkably poor.

Contact me at the email address in my HN account and we can arrange for a human with a soul and feelings to write the docs from scratch assuming you have a price in mind that values the nature of my talent and experience.

Wow, you're Xe Iaso! I've reached out.

Out of curiosity, I ran the PDF through pangram and it seemed to flag nearly the entire thing as AI. I recognize these aren't perfect detectors, but they can give signals if nothing else. Perhaps it needs more soul injected!

https://www.pangram.com/history/93f9ec71-f7b3-4680-86b1-ff12...

Perhaps these "ai detectors" are snake oil

There’s definitely a snake oil component, but Pangram is unbelievably accurate. Creepily so in my opinion

How do you evaluate that?

Well, I've tried to get around it for our corporate SEO blogging strategy, and I've found that it's just not possible to do it (even with really crazy techniques where you have different models combined to produce the output, or you change your prompting style massively). The minute I take the same article that the LLM gave me and I rewrite it in my own voice (meaning just take the information and topics, but rewrite it from scratch), the post works immediately and passes as 100% human on Pangram.

The only thing that gets around that is StealthGPT, but it mangles your intent in the output so badly that it's easier to just write the thing yourself.

Yeah, this doc is really interesting. It has some absolutely claude-fried lines like:

> A hook is Koa-style middleware: it reifies an endomorphic continuation

> Five forms, each on tool.call;

But on the other hand uses distinctly human phrases like “one may” and “etc./e.g.” that I rarely see LLMs use. Not sure what to think.

Maybe Claude is RLHFd primarily on texts by mpoteat and that’s why it talks this way

I know it's a joke but if you look at many of the key AI researchers papers (written pre-LLM mass adoption) you can see some similarities with how LLMs structure their output.

I'd love to do some stylometry on this...

I have found that Opus 5 and Fable love bringing up category theory at the drop of a hat.

Not beating the allegations on "Claude doesn't speak human because Anthropic employees don't speak human."

I am going to be called on that one, but I have to call on your bullshit here. You didn't write this.

It's a register that would be great for some tabletop games or pop science writing, but in this context it could really use a technical editor to aggressively remove phrasing like "keeping the fold neatly uniform" and "affordance surface", as well as change things like "hooks live in a hooks.json file, today of four extant types" into plain technical language ("there are four types of hook that can be defined in hooks.json").

> Ouch! Much of this verbiage was dictated by me personally; I just have a fairly distinct register some might consider inscrutable.

I do notice that the more Claude-generated stuff I read, the more it creeps into my daily usage, and I suspect I don't read nearly as much of it as an Anthropic Employee would, so I could believe that. Though "much of" isn't the same as "written with zero AI generation/rephrasing/etc."

Anyway, that aside, something I would like to see is an example of something that's possible with this system that isn't, or isn't easily, possible with existing Claude hooks. Right now it reads like "Here's a cool thing! Here's how it works! And here's this other similar system we have! Here's how that works!" But there's no summary of the differences, why I'd use this over regular hooks, and so on. Or at least not that I saw on quick skim, and I'd be looking for that to be mentioned as early as possible, so I know if the rest is worth reading.

What if we have it all backwards? What if Claude-speak, as some like to call it, is actually caused by this one dude dictating the documentation?

her writing style isn't normally this claudish though!

Well regardless of the origins of Claude-speak, I'm sure millions of humans are picking up some of its idioms, and at least some fraction of it will enter standard English in some decades

Your writing is fine, documentation is hard and nobody is perfect at launch. I can all but guarantee I have more editing experience than the commenter and trust me, you’re fine.

I think the various recent articles about agent output using ASD-STE100 Simplified Technical English are quite pertinent here. For example:

"Agent Skill to Force Docs in ASD-STE100 Simplified Technical English"

https://news.ycombinator.com/item?id=49114639

If the direct link isn't working for anyone else (looks like it's some AWS pre-signed one maybe tied to IP): https://github.com/user-attachments/files/31802150/EXTERNAL....

Here's a palatable, clear version:

https://pdfhost.io/v/2CVhPGy9Kw_CLEAR_Function_Hooks_Core_Ar...

Writing documentation is one of the most often mentioned uses of LLMs. I suppose if Anthropic wouldn't be doing it it would put into question why anyone else would.

I’m curious… would you talk to them like this in person? The only ‘egregious’ thing I read here was your reaction. Maybe you could consider acting more human?

> they are noun phrases and not sentences at all? I’m pretty sure that any decent pre-LLM NLP-based grammar checker would correctly flag half the sentences in Claudish. Also, whatever variant of Claude wrote this thing can’t even capitalize around semicolons consistently with itself, let alone consistently with how English has been written for at least a century.

Probably just a case of a company hoping their scale can change the societal standard faster than they can be bothered to match the standard.

You'll talk like 2023 unsupervised TikTok generators and you'll be happy.

Reply on news.ycombinator.com