docs: align CLAUDE.md templates across project, README, and guide#467
Conversation
The three CLAUDE.md templates (our own, README snippet, AI agent guide) had diverged — different commands, different structure, missing workflow steps. Unify them around a consistent 5-step workflow and categorized command reference. - CLAUDE.md: add codegraph workflow section with commands hooks don't cover (where, audit, context, fn-impact, query, path, search, etc.) - README: compact the template, point to guide for full version - AI agent guide: expand template with all commands organized by category, add semantic search guidance and hooks section
|
Claude finished @carlos-alm's task —— View job PR Review: CLAUDE.md Template AlignmentReviewing this documentation alignment PR following the 5-phase analysis framework. Todo List
Root Cause AnalysisProblem Being Solved: Template fragmentation across three key documentation files was creating inconsistent agent guidance. The CLAUDE.md had minimal workflow guidance, README had a compressed template that omitted important commands, and the AI Agent Guide lacked the same workflow structure - leading to suboptimal agent behavior patterns. Why This Approach: Standardizing all three around the same 5-step workflow (orient → locate → understand → context → impact → verify) with consistent command syntax ensures agents get the same high-quality guidance regardless of which documentation they reference. Risk Assessment: Very low risk - purely additive documentation changes that improve consistency without breaking any existing functionality. Backlog Compliance
Critical ConcernsNone. This is a well-executed documentation improvement that addresses a real consistency problem. Documentation Quality AssessmentCLAUDE.md Changes (
README.md Changes (
AI Agent Guide Changes (
Consistency Verification:
Final Recommendation
|
Greptile SummaryThis PR aligns the three codegraph documentation templates (CLAUDE.md, README template, AI Agent Guide template) around a shared 5-step workflow and consistent command syntax. The README is compacted from ~75 to ~25 lines, CLAUDE.md gains a new categorized command reference, and the AI Agent Guide expands to 30+ commands with workflow steps and semantic search guidance.
Confidence Score: 3/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[CLAUDE.md] -->|"5-step workflow<br/>(missing step 5)"| D[Shared Workflow]
B[README.md template] -->|"5-step workflow<br/>compacted to 25 lines"| D
C[AI Agent Guide template] -->|"5-step workflow<br/>30+ commands"| D
D --> E["1. Orient — where, audit --quick"]
D --> F["2. Understand — context"]
D --> G["3. Impact — fn-impact"]
D --> H["4. Verify — diff-impact --staged"]
B -->|"links to"| C
style A fill:#ff9,stroke:#333
style B fill:#9f9,stroke:#333
style C fill:#9f9,stroke:#333
Last reviewed commit: 831500f |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| 1. `codegraph where <name>` — find where the symbol lives | ||
| 2. `codegraph audit --quick <target>` — understand the structure | ||
| 3. `codegraph context <name> -T` — get full context (source, deps, callers) | ||
| 4. `codegraph fn-impact <name> -T` — check blast radius before editing |
There was a problem hiding this comment.
Missing "After modifying code" step
The README template (line 619-620) and AI Agent Guide template (line 880-881) both include an "After modifying code" section with step 5 (codegraph diff-impact --staged -T), but CLAUDE.md jumps from step 4 directly to "Navigation". Since this PR's goal is to align all three templates around a consistent 5-step workflow (orient → understand → context → impact → verify), this omission undermines that alignment.
| 4. `codegraph fn-impact <name> -T` — check blast radius before editing | |
| 4. `codegraph fn-impact <name> -T` — check blast radius before editing | |
| ### After modifying code: | |
| 5. `codegraph diff-impact --staged -T` — verify impact before committing |
There was a problem hiding this comment.
Fixed — added the missing 'After modifying code' step 5 (codegraph diff-impact --staged -T) to CLAUDE.md, completing the 5-step workflow alignment across all three templates.
1 participant
Summary
All three now share the same workflow structure (orient → understand → context → impact → verify) and consistent command syntax.
Test plan