How I Keep Project Notes

Summary

• This post records the operating principles I set when I first opened this blog.
• The detailed writing rules are now managed in the repository's AGENTS.md.
• Public posts should preserve real context while clearly separating evidence, verification scope, and information that should not be published.

Context

I started this blog not as a collection of finished tutorials, but as a place to record what I learned while building and operating real projects.

A useful note should still be usable when I reread it later. So each post should leave behind the problem context, evidence I checked, judgment process, and the rule I want to avoid relearning next time.

At first, this post itself was close to the writing standard. As the blog grew, more repository-level rules appeared: images, Excalidraw diagrams, SEO metadata, private-post handling, and security checks before publication.

The current detailed writing standard now lives in AGENTS.md. This post remains as the initial operating principle explaining why I keep notes this way.

Basic Post Structure

When possible, project notes follow this flow.

## Context

## Problem

## Initial Hypothesis

## Evidence Checked

## Fix

## Verification

## Lesson

## What I Will Do Next Time

## References

Not every post has to follow this order exactly. Retrospectives can focus on feedback and behavior changes. Experiments can focus on hypotheses and results. Incident records can focus on evidence and verification. Still, I try to keep a ## Summary, the problem context, the evidence checked, and the next rule.

Publication Standard

When publishing project notes, I keep the real context but remove information that should not be public.

• Do not include tokens, accounts, internal URLs, or customer names.
• Write incident or cost records around causes and decision criteria.
• Keep only the code snippets needed to explain the problem.
• Separate assumptions from confirmed facts.
• Do not treat private posts as secure storage. Clean up sensitive information and screenshots before publication.

Image and Diagram Standard

When possible, place a situation diagram near the top of the post.

![상황 설명 도식](./situation-diagram.png)

The diagram does not replace the post. Colors, arrows, and boxes are supporting tools that make the problem structure easier to see. The core judgment still has to appear again in prose.

For screenshots and experiment images, the alt text and surrounding paragraph should explain what is visible. If an image is evidence, the post should also tell the reader where to look.

Tag Standard

Tags should use words that make the post easy to find again later.

• debugging
• deployment
• analytics
• frontend
• backend
• infra
• product
• retrospective
• security
• seo

First Operating Principle

I should not postpone writing because a post feels too long. If I learn one thing from a project, that is enough for one note.

But I should not publish carelessly either. The current standard is simple.

• Write only what I actually checked.
• Do not describe unverified outcomes as success.
• Use official external documentation first.
• Use AGENTS.md to check frontmatter, images, publication scope, and verification.