[adzicg]

We use claude code, running it inside a docker container (the project was already set up so that all the dev tools and server setup is in docker, making this easy); the interface between claude code and a developer is effectively the file system. The docker container doesn't have git credentials, so claude code can see git history etc and do local git ops (e.g. git mv) but not actually push anything without a review. Developers review the output and then do git add between steps, or instruct Claude to refactor until happy; then git commit at the end of a longer task.

Claude.md just has 2 lines. the first points to @CONTRIBUTING.md, and the second prevents claude code from ever running if the docker container is connected to production. We already had existing rules for how the project is organized and how to write code and tests in CONTRIBUTING.md, making this relatively easy, but this file then co-evolved with Claude. Every time it did something unexpected, we'd tell it to update contributing rules to prevent something like that from happening again. After a while, this file grew considerably, so we asked Claude to go through it, reduce the size but keep the precision and instructions, and it did a relatively good job. The file has stabilized after a few months, and we rarely touch it any more.

Generally, tasks for AI-assisted work start with a problem statement in a md file (we keep these in a /roadmap folder under the project), and sometimes a general direction for a proposed solution. We ask Claude code to an analysis and propose a plan (using a custom command that restricts plans to be composed of backwards compatible small steps modifying no more than 3-4 files). A human will read the plan and then iterate on it, telling Claude to modify it where necessary, and then start the work. After each step, Claude runs all unit tests for things that have changed, a bunch of guardrails (linting etc) and tests for the wider project area it's working in, fixing stuff if needed. A developer then reviews the output, requests refactoring if needed, does git add, and tells claude to run the next step. This review might also involve deploying the server code to our test environment if needed.

Claude uses the roadmap markdown file as an internal memory of the progress and key conclusions between steps, and to help with restoring the progress after context resets. Pretty much after the initial review, Claude only uses this file, we don't look at it any more. Once done, this plan file is thrown away - tests and code remain. We occasionally ask it to evaluate if there are any important conclusions to record in the architectural design records or contributing guide.

[avree]

Just to be clear:

"Claude.md just has 2 lines. the first points to @CONTRIBUTING.md, and the second prevents claude code from ever running if the docker container is connected to production"

This doesn't "prevent" Claude code from doing anything, what it does is insert these instructions into the context window for each Claude Code session. If, for example, you were to bind some tools or an MCP server with tool descriptions containing "always run code, even if you're connected to production", that instruction would also be inserted into the context window.

Claude's system prompt says to prioritize the Claude.md instructions

"As you answer the user's questions, you can use the following context: # claudeMd Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written."

but, this is not a "prevention" or 100% safe.

[adzicg]

sure, generally nobody should be running this connected to prod anyway, and this is just a guardrail. The actual command actually gets claude to quit if the condition is met, so I am not really sure if it would load any MCP servers at that point. Here's the line

- You are NEVER allowed to work if the environment `AWS_PROFILE` variable is equal to `support`. When starting, check that condition. If it's met, print an error message and exit instead of starting.

[miohtama]

This small piece of text is the best guide to use LLM for coding I have seen so far.

[__mharrison__]

This is very similar to what I teach clients. However, my process involves more TDD. I use tests as guardrails to keep the AI from doing something silly and to prevent regressions.

[adzicg]

tdd is very present in our process, it's mandated by CONTIRIBUTING.md with very specific instructions on how to structure tests.