From 527a689f919b80048232f741416fbe6303aa4b10 Mon Sep 17 00:00:00 2001 From: David Johnston Date: Wed, 1 Jul 2026 13:57:53 +1000 Subject: [PATCH 1/5] Create the_case_for_an_ai_header.mdx --- .../posts/the_case_for_an_ai_header.mdx | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 src/routes/posts/the_case_for_an_ai_header.mdx diff --git a/src/routes/posts/the_case_for_an_ai_header.mdx b/src/routes/posts/the_case_for_an_ai_header.mdx new file mode 100644 index 0000000..08a65e1 --- /dev/null +++ b/src/routes/posts/the_case_for_an_ai_header.mdx @@ -0,0 +1,75 @@ +--- +meta: + title: The case for adding a 'this file was generated by AI' header + description: It helps not gaslight anyone reading the code + dateCreated: 2026-07-01 + +tags: + - "ai" + - "ai_prompts" + +--- + + +I have recently taken to adding this instruction to my coding agent prompts: + +```md +## Agent Instructions + +When creating a new file add the following header to the top of it + +```typescript +/** + * 🤖 + * This file was created with AI + * + * Harness: (harness name) + * Model: (model name) + * Supervising engineer: (get this from git config) + * + * Level of human supervision: None (None is the default, but if in an interactive session with a human you can ask to elevate it) + * + * + */ + +``` + +Exceptions: +- JSON files and anything else that would break with the presence of the header +``` + + +This is simple enough prompt that is hard to get wrong. + +## But why? + +Mostly to improve signal when working in teams. + +If a colleague creates a pull request with dozens of files of pristine, comprehensively tested code, this immediately triggers a 'this looks AI generated to me' kind of though. + +_Which is fine_. + +But: + +- If we're embracing AI, then let's not be embarrassed about it. +- It makes it really clear to your colleagues which bits are AI generated. It's _signal_ we're not pretending we wrote this ourselves. +- It makes us as a human consider 'how have we sense checked this' or 'how are we assessing correctness'? + + +## What's wrong with it + +- You could argue that if we have configured our AI to be commiting, and it has the 'Co-Authored-By:` note in the commit message that this suffices to understand where the code from, but: + - That commit message will be lost if squash merging + - Some times commits are made manually + - Commit messages are not nearly as readily apparent as code + +- It might be a good source of signal for the first time the file is created, but as the file is modified, by human or otherwise, the header becomes a less clear source of signal, but: + - A lot of AI generated code _is_ going to be this 'one and done' style code + - That's where diving in to the commit history for the file can help + +- Communicating just what the level of human overview/intent is, is messy + - Say you did a TDD approach where you carefully supervised the AI in creating tests cases, but the actual code, in 10 different files was purely AI generated - how exactly do you communicate this? + - Copy paste that message to each header file? + - Have a `HUMANS.md` file in the folder that explains it? + - Just explain it once in the test file, and hope that the future reader knows to look there? + From d987e34a404f6e1bd05aa75be7c7e927bca50772 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 03:59:26 +0000 Subject: [PATCH 2/5] Fix typos in the_case_for_an_ai_header.mdx Co-authored-by: David Johnston --- src/routes/posts/the_case_for_an_ai_header.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/routes/posts/the_case_for_an_ai_header.mdx b/src/routes/posts/the_case_for_an_ai_header.mdx index 08a65e1..bd74cd5 100644 --- a/src/routes/posts/the_case_for_an_ai_header.mdx +++ b/src/routes/posts/the_case_for_an_ai_header.mdx @@ -39,13 +39,13 @@ Exceptions: ``` -This is simple enough prompt that is hard to get wrong. +This is a simple enough prompt that it's hard to get wrong. ## But why? Mostly to improve signal when working in teams. -If a colleague creates a pull request with dozens of files of pristine, comprehensively tested code, this immediately triggers a 'this looks AI generated to me' kind of though. +If a colleague creates a pull request with dozens of files of pristine, comprehensively tested code, this immediately triggers a 'this looks AI generated to me' kind of thought. _Which is fine_. @@ -58,7 +58,7 @@ But: ## What's wrong with it -- You could argue that if we have configured our AI to be commiting, and it has the 'Co-Authored-By:` note in the commit message that this suffices to understand where the code from, but: +- You could argue that if we have configured our AI to be committing, and it has the `Co-Authored-By:` note in the commit message, that this suffices to understand where the code came from, but: - That commit message will be lost if squash merging - Some times commits are made manually - Commit messages are not nearly as readily apparent as code @@ -68,7 +68,7 @@ But: - That's where diving in to the commit history for the file can help - Communicating just what the level of human overview/intent is, is messy - - Say you did a TDD approach where you carefully supervised the AI in creating tests cases, but the actual code, in 10 different files was purely AI generated - how exactly do you communicate this? + - Say you did a TDD approach where you carefully supervised the AI in creating test cases, but the actual code, in 10 different files, was purely AI generated - how exactly do you communicate this? - Copy paste that message to each header file? - Have a `HUMANS.md` file in the folder that explains it? - Just explain it once in the test file, and hope that the future reader knows to look there? From aadf79fb29eef7e09183c28c655d7120e494922e Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 04:01:40 +0000 Subject: [PATCH 3/5] Revert unnecessary 'it's' wording change per feedback Co-authored-by: David Johnston --- src/routes/posts/the_case_for_an_ai_header.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/posts/the_case_for_an_ai_header.mdx b/src/routes/posts/the_case_for_an_ai_header.mdx index bd74cd5..9b4b2a1 100644 --- a/src/routes/posts/the_case_for_an_ai_header.mdx +++ b/src/routes/posts/the_case_for_an_ai_header.mdx @@ -39,7 +39,7 @@ Exceptions: ``` -This is a simple enough prompt that it's hard to get wrong. +This is a simple enough prompt that is hard to get wrong. ## But why? From eb318f0d70fe08c8e6814b3713917ad0bae38f1a Mon Sep 17 00:00:00 2001 From: David Johnston Date: Wed, 1 Jul 2026 14:03:49 +1000 Subject: [PATCH 4/5] Update the_case_for_an_ai_header.mdx --- src/routes/posts/the_case_for_an_ai_header.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/routes/posts/the_case_for_an_ai_header.mdx b/src/routes/posts/the_case_for_an_ai_header.mdx index 9b4b2a1..adf692c 100644 --- a/src/routes/posts/the_case_for_an_ai_header.mdx +++ b/src/routes/posts/the_case_for_an_ai_header.mdx @@ -18,7 +18,7 @@ I have recently taken to adding this instruction to my coding agent prompts: When creating a new file add the following header to the top of it -```typescript +\`\`\`typescript /** * 🤖 * This file was created with AI @@ -32,7 +32,7 @@ When creating a new file add the following header to the top of it * */ -``` +\`\`\` Exceptions: - JSON files and anything else that would break with the presence of the header From e9015d8877bacf8cd3a78c1cc6869f5540a0963d Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 04:08:32 +0000 Subject: [PATCH 5/5] Fix nested code fence rendering by using a longer outer fence Co-authored-by: David Johnston --- src/routes/posts/the_case_for_an_ai_header.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/routes/posts/the_case_for_an_ai_header.mdx b/src/routes/posts/the_case_for_an_ai_header.mdx index adf692c..b5197a8 100644 --- a/src/routes/posts/the_case_for_an_ai_header.mdx +++ b/src/routes/posts/the_case_for_an_ai_header.mdx @@ -13,12 +13,12 @@ tags: I have recently taken to adding this instruction to my coding agent prompts: -```md +````md ## Agent Instructions When creating a new file add the following header to the top of it -\`\`\`typescript +```typescript /** * 🤖 * This file was created with AI @@ -32,11 +32,11 @@ When creating a new file add the following header to the top of it * */ -\`\`\` +``` Exceptions: - JSON files and anything else that would break with the presence of the header -``` +```` This is a simple enough prompt that is hard to get wrong.